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PREFACE 



This publication i s to be used for planning purposes only. Any information 
contained herein is subject to change. For final information concerning 
any topic discussed in this publication, consult the Version 1.1 manuals 
listed beloM Mhen they become available. 

This publication provides the information required to design applications 
that use Version 1.1 of the Event Driven Executive, the Multiple Terminal 
Manager, and the Indexed Access Method. 



HOU THIS HANUAL IS ORGANIZED 



• Part 1 describes Version 1.1 of the Event Driven Executive and points 
out the enhancements it provides over Version 1.0. 

• Part 2 describes the Multiple Terminal Manager, which you can use to 
simplify the definition of transaction-oriented applications. 

• Part 3 describes the Indexed Access Method, which you can use to 
access and maintain your data in a keyed (indexed) organization. 

Before reading this manual, you should be familiar with the Event Driven 
Executive. See the list below for publications that can help you. 



RELATED PUBLICATIONS: 

The following publications are now available for Version 1.0 of the Event 
Driven Executive. The Version 1.1 publications will be released in Octo- 
ber, 1979, under the same numbers and titles (except as noted). 

• IBM Series/1 System Summary , GC34-0285. 

• IBM Series/1 Event Driven Executive System Guide , SC34-0312. 

• IBM Series/1 Event Driven Executive Utilities, Operator Commands, and 
Program Preparation , SC34-0313. 

Note. The Version 1.1 release of this document will be titled? IBM 
Series/l Event Driven Executive Utilities> Commands, Program Prepara- 
tion and Messages and Codes , 5C3^-0313. 

• IBM Series/1 Event Driven Executive Language Reference , SC3^-0314. 

• IBM Series/1 Event Driven Executive Macro Assembler, SC3^-0317. 



Preface i i i 



IBM Serfes/l Event Driven Executive Communfcati ons Guide » SC34-0316. 

Note. The Version 1.1 release of this document will bes IBM Series/l 
Event Driven Executive Communications and Terminal Applications 
Guide, 5C34-0316. 
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PART 1: EVENT DRIVEN EXECUTIVE 



INTRODUCTION 



Version 1.1 of the Event Driven Executive* available in 
October 1979, expands the scope of the data processing 
solutions possible with the Event Driven Executive. 
Improvements include^ 

• Support for 128KB of storage on the ^952 

• Applications programs up to 64KB 

• Cross-partition communication capability 

• Diagnostic and recovery improvements 

The changes that make this possible are described in this 
planning guide. 

Version 1.1 of the Event Driven Executive system includes 
service releases of each of the following licensed pro- 
grams- 
Basic Supervisor and Emulator (5719-XSl) 

Utilities (5719-UT3) 

Program Preparation Facility (5719-XX2) 

Macro Assembler (5719-ASA) 

Macro Library (5719-LM5) 

Macro Library/Host (5740-LM2) 

COBOL Compiler and Resident Library (5719-CB3) 

COBOL Transient Library (5719-CB4) 

FORTRAN IV Compiler and Object Library Version 2 
(5719-F02) 

Sort/Merge (5719-SM2) 

Mathematical and Functional Subroutine Library 
(5719-LM3) 






The following new licensed programs have also been 
announced for use with Version 1.1 of the system and will 
be available in October 1979. 
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• Indexed Access Method (5719-AI13) 

• Multiple Terminal Manager (5719-MSl) 

These new programs are also described in this planning 
guide. 



ADDRESS TRANSLATOR SUPPORT 



VERSION 1.0 



VERSION 1.1 



The Event Driven Executive (EDX) operating system for the 
Series/1 currently supports the address translator fea- 
ture of the 4952 and 4955 processors. The programs execut- 
ing in each storage partition have direct access to the 
functions and data areas in the supervisor^ in much the 
same way as a program executing in a non-address trans- 
latedy single partition system. Although this mechanism 
offers the advantages of conceptual simplicity and com- 
patibility with earlier versions of the operating system* 
it has two drawbacks. First » segmentation registers sire 
used to map the system area into each partition defined by 
the user. In systems with processor storage approaching 
128K bytes and two sets of segment registers, the result 
may be an inadequate number of segmentation registers to 
map the entire storage area. Thus, processor storage can 
exist which cannot be accessed by either user or system 
tasks. Second, the user application may be 
size-constrained by the necessity to leave 20-32KB or more 
for the system area in each 64KB partition. 

The system requires that two facilities be available to 
user programs and system utilities regardless of the 
addressing mechanism used. These are the ability to invoke 
supervisor functions through Series/1 assembler language 
instructions or the Event Driven Language and the ability 
to reference system data areas, again in either a direct 
or indirect fashion. As noted above, the current version 
of EDX provides these functions by logically mapping the 
supervisor into each partition. 



Version 1.1 of EDX provides a supervisor that resides only 
in partition 1, thus making it possible to support appli- 
cation programs up to 64K bytes in length in the other 
partitions. Elimination of redundant mappings of the sys- 
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tern &rea frees more of the processor's segmentation regis- 
ters for use in addressing unique physical storage* thus 
increasing the amount of storage that can be effectively 
put to use on processors such as the 4952. The ability to 
optionally map a porti on of the system area into each pai — 
tition provides the capability for shared storage areas 
(such as $SYSCOM) without wasting large amounts of appli- 
cation space on other control program modules as well. 
Figure 1 illustrates some of the storage configurations 
now possible with Version 1.1. 

Another advantage of the new storage map is that it pro- 
vides increased protection of the system area from acci- 
dental modification by applications. Previously* a 
program error could accidentally damage the system and 
affect all programs and partitions. Because the Version 
1.1 system area resides in partition 1 only* the chance of 
accidental modification by programs in other partitions 
is considerably reduced. 

To complement the storage map improvement the enhanced 
address translator support includes several extensions to 
system functions for the multi -parti ti on environment. 
These extensions make it possible to move data and signal 
events and manage resources across partition boundaries* 
thus making multiple partition applications easier to 
design and implement. These facilities are described in 
more detail under the heading "Multi -Parti ti on Exten- 
si ons." 

Version 1.1 also contains improved diagnostic and recov- 
ery capability. Optional facilities include I/O error 
logging* a task error recovery exit* a program exception 
trace, and a storage dump. These facilities are described 
in more detail under the heading "Diagnostic and Recovery 
Improvements. " 



Version 1.1 preserves all the standard Event Driven Execu- 
tive application program interfaces and as many of the 
application implementation techniques as possible. 
Version 1.1 is compatible with Version 1.0 in terms of 
source programs, data sets and functional content. Each of 
these is explained more fully below. In general* you may 
expect that applications written to run on Version 1.0 
will run on Version 1.1 after recompi lati on . Since most 
applications written for the Event Driven Executive FDP 
Version 2 would also run on Version 1.0 of the licensed 
program* the information in this guide is also applicable 
to them. 
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Figure 1. Possible Storage Configurations 
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SOURCE PROGRAM COMPATIBILITY 
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COBOL and FORTRAN programs are completely source compat- 
ible and require only that they be recompiled using Vei — 
sion 1.1 of the COBOL or FORTRAN compiler. An additional 
module of less than 200 bytes will be automatically 
included (by Autocall) during link-edit. Execution of 
COBOL programs will require Version 1 . 1 of the COBOL Tran- 
sient Library. Version 1.1 of COBOL and FORTRAN will be 
available concurrent with Version 1.1 of supervisor and 
will be automatically shipped to existing licensees. 

Event Driven Language (EDL) and Series/1 Assembler Lan- 
guage programs that use standard application interfaces 
are source compatible. Refer to the topic below titled 
"Application Program Interfaces" for a list of source com- 
patible interfaces. However, any programs with explicit 
dependencies on access to the system area may* 

1. Be required to execute in partition 1 only so that 
unrestri cted access to the system area is possible. 

2. Require that the option to map some or all of the sys- 
tem area into each partition be used to provide the 
ability to reference system area control blocks. 

3. Require source modification to utilize the cross 
address space capabilities added to various functions 
i n Versi on 1.1. 

Recompi lat i on of the Event Driven Language or assembler 
language programs requires Version 1.1 of the appropriate 
program preparation vehicle. All these releases will be 
available concurrent with Version 1.1 of the Supervisor 
and Emulator and will be automatically shipped to existing 
licensees. The following program preparation vehicles may 
be used: 

1. Program Preparation ($EDXASM) Version 1.1 (for pro- 
grams consisting exclusively of Event Driven Language 
statements) . 

2. Macro Library Version 1.1 and Macro Assembler Version 
1.1. If it is desired to compile programs on Version 
1.0 for later execution on a Version 1.1 system, the 
Version 1.1 Macro Library can also be used with the 
Version 1.0 Macro Assembler. 

3. Macro Library/Host Version 1.1 and any current release 
of the Series/1 370 Host Assembler. 

Application programs that contain Series/1 assembler lan- 
guage instructions will require 1-3 additional modules to 
be link-edited with the application. These modules are 
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provided with the Version 1.1 supervisor for the purpose 
of handling the special interface used by assembler lan- 
guage routines under EDX. Most assembler language applica- 
tions will require only the basic RETURN interface module 
(about 40 bytes) but some applications may require addi- 
tional modules that support the special interfaces SVC» 
SETBUSY and SUPEXIT. The interface modules total approxi- 
mately 200 bytes and can be automatically included where 
needed with the AUTOCALL facility of $LINK if EXTRN state- 
ments for the desired modules are included with the pro- 
gram. See the "Special Considerations" topic for more 
information. 



APPLICATION PROGRAM INTERFACES 



The primary application program interface is documented 
in the Event Driven Executive Language Reference manual. 
Users of COBOL or FORTRAN may also view their respective 
language reference manuals and users guides as their 
interface. In addition to these» certain other interfaces 
and data areas are available for reference and use by 
application programs. These are the following^ 

• The Branch interfaces named RETURN, SETBUSY, SUPEXIT 
and SVC and their respective parameter lists. 

• The CALL interface for DSOPEN, including its parame- 
ters and data area. 

• The CALL interface for SETEOD including its parameter 
list and data area. 

• The following interfaces as described in the 
Communications Guide ? BSCOPEN, BSCCLOSE, BSCREAD, 
BSCWRITE, BSCIOB, and TP (all functions). 

• The first two words of the Task Control Block (TCB) 
system data area. 

• The first two words of the Data Set Control Block 
(DSCB). 

Programs should use only the above interfaces so that they 
will be source-statement compatible across releases of 
EDX. 
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DATA SET COHPATIBILITY 



Data sets created or updated using Version 1.0 can be used 
on Version 1.1 without change. 



FUNCTIONAL CONTENT COMPATIBILITY 



STORAGE SIZES 
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All the functions defined in the Language Reference 
Manual > the Utilities Operator Commands and Program 
Preparati on and the Communications Guide for Version 1,0 
are also supported by Version 1.1. 



Version 1.1 of the Supervisor and Emulator is slightly 
larger than Version 1.0. For planning purposes you may 
assume that the system area of identical configurations 
will increase by approximately 5% for a configuration with 
6^KB or less and by approximately 10% for configurations 
with more than 64KB of storage. Actual increases will 
depend on the particular functions included in each sys- 
tem. 

Systems installed on a 4952 processor with 128KB of stoi — 
age will gain the use of up to 32KB of additional storage 
in return for the 2-4KB increase in control program size. 
Users of the 4955 processor with greater than 64KB will 
also find that the increase is offset by application 
improvements made possible by the availability of larger 
application spaces and the new mult i -part i ti on exten- 
sions. Potential benefits include the ability to avoid the 
need for complex overlays or applications that must be 
split apart so they can be executed in separate parti- 
tions* and the ability to keep more data in storage 
instead of spilling it to disk to save space. 

Changes in program size are expected to be minimal for 
most applications written in the Event Driven Language. A 
straightforward program with a single task and no atten- 
tion lists (ATTNLIST) will increase about 50 bytes. Each 
attention list will expand about 120 bytes (see "Special 
Considerations" for more information on ATTNLIST). 
Programs containing Series/1 assembler language code (in- 
cluding all COBOL and FORTRAN programs) will require an 
additional 50 to 200 bytes because of the inclusion of the 
interface modules described in the section on "Source Pro- 
gram Compatibility." 
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MULTI-PARTITION EXTENSIONS 



As part of the changes in the address translator support 
several system functions have been altered to accommodate 
the new environment. These changes remove many of the 
restrictions of the Version 1.0 address translator and 
allou applications written in the Event Driven Language or 
assembler language to take maximum advantage of the 
multi -parti tion environment. With the Version 1.1 address 
translator support it is possible toi 

• Move data directly from the executing program's parti- 
tion to another* or vice versa, using the MOVE 
i nstructi on. 

• Enqueue or dequeue (ENQ/DEQ) on a resource (QCB) in 
another partition without the use of a common area 
($SYSCOM). 

• LOAD a program in another partition and pass parame- 
ters to it or wait for its completion. 

• READ or WRITE using a buffer in a partition other than 
the executing program's. 

• ATTACH a task in another partition. .-. 

; ] 

• WAIT or POST an event (ECB) in a partition other than ""^'-^ 
the invoker's and without a common area ($SYSCOM). 

• Locate a program by name and determine its address and 
partition. This allows independently loaded programs 
to find each other at execution time without using a 
common area ($SYSCOM). 



DIAGNOSTIC AND RECOVERY IMPROVEMENTS 



I/O ERROR RECORDING 



Included in Version 1.1 is the optional ability to log the 
occurrence of hardware errors on a data set. This facili- 
ty, which is used by EDX device services and is available 
to usei — written device handlers and EXIO users, provides 
error data to assist in the detection and correction of 
hardware errors. A utility to print the contents of the 
log data set is included. 
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TASK ERROR EXIT 



Application programs can elect to process errors them- 
selves instead of relying on standard system actions. This 
enables diagnostic and recovery actions to be tailored to 
each user's application environment. Each task can iden- 
tify a routine to receive control if a processor malfunc- 
tion or program exception occurs during the execution of 
the task. If an error occurs, execution of the task is 
resumed at the task error exit routine in lieu of the 
standard system action of terminating the task. 



SYSTEM AREA PROTECTION 



Isolation of the system area from all but one application 
partition constrains most application errors to a single 
partition instead of allouiing impact to the entire machine 
through damage to the system area. 



PROGRAM EXCEPTION TRACE 



Program exception data can be captured in an in-storage 
table, providing a chronological history of exceptional 
conditions for use in debugging. 



STORAGE DUMP 



A storage dump utility provides the ability to stop on 
program exceptions and record the contents of the storage 
in a data set. A second utility prints the dump data set. 



SPECIAL CONSIDERATIONS 



Certain interfaces and implementation techniques have 
been affected by the Version 1.1 address translator 
changes. Application programs that use any of the inter- 
faces or techniques described in this section will require 
review to determine if changes will be necessary or desir- 
able in the new execution environment provided by Version 
1.1. These considerations are in addition to those listed 
under "Compatibility." 
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Applications that depend on explicit reference to data 
Ccontrol blocks) in the system Qrea are definitely 
affected by the new multi -parti ti on environment because 
the system area is not addressable by the program unless 
special action is taken. Data areas such as the DDB 
(disk)> CCB (terminal) and CMDTABLE (command Table) are 
not generally accessible in a multi -parti ti on system. 
There are three approaches that can be used to move appli- 
cations with this dependency onto a multiple partition 
Version 1.1 system. 

1. Execute the application in partition 1 only. Since the 
system area also resides in partition 1, the applica- 
tion will have unrestricted access to it without the 
need for any changes. 

2. Map some or all of the system area into every partition 
so that the desired data areas are accessible from 
es/erv partition. This requires generation of a system 
using a new, optional parameter on the SYSTEM state- 
ment, but it requires no changes to the application 
program. 

3. Alter the application to use the new mult i -part i ti on 
functions to obtain the desired data. Some applica- 
tions may be able to use the new functions exclusively 
instead of depending on direct use of the system area. 
This is recommended where possible because the consent 
and format of the system area are subject to change. In 
addition, it should be possible to eliminate the need 
for $SYSCOM from many applications. 



INVOKING PROGRAMS THAT RESIDE IN THE SYSTEM AREA 



Certain programs that reside in the system area may be 
branch-entered by assembler language application pro- 
grams. Only the following four entry point names are sup- 
ported: RETURN, SVC, SETBUSY and SUPEXIT. To use these 
entry points in a Version 1.1 system it will be necessary 
to link-edit ($LINK) additional module(s) with the appli- 
cation program. No source code modifications are 
required. The additional modules, which are provided with 
the Version 1.1 supervisor and emulator, are about 200 
bytes in total size. Only the module(s) required for the 
particular entry point(5) in the program need be included. 
Mapping the system area into all partitions does not elim- 
inate the requirement to use the linkage module. 
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USER-URITTEN SUPERVISOR EXTENSIONS 



In generals usei — written extensions to the supervisor 
will require careful review for dependencies on address- 
ing data in the application's partition. The keyboard task 
will always execute with address key because it phys- 
ically resides in partition 1. Change Partition ($CP) will 
no longer change the processor address key register; 
instead the new partition value will be placed in a TCB 
field, TCBAD5. System functions must use this field to 
determine the actual partition in use. The TCBAKR field 
should not be used for this purpose. 



VIRTUAL TERMINALS 



X 
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Applications that use virtual terminals may require mod- 
ification if the TERMINAL statement defining the virtual 
terminal is contained in the application program rather 
than in the system configuration module ($EDXDEFS). 
Commencing with Version 1.1, all TERMINAL statements must 
be in partition 1 and application programs in other parti- 
tions must use an lOCB statement to gain access to the 
virtual terminal. To help provide source compatibility, 
TERMINAL statements coded in application programs will 
automatically be converted to lOCB statements during 
assembly. However, TERMINAL statements with the same 
names and parameters as those in the application program 
must be added to the system configuration module 
($EDXDEFS). 

The following example, which is explained in the "Advanced 
Topics" section, the Version 1.0 System Guide , 
illustrates a typical use of virtual terminals^ 

A TERMINAL DEVICE=VIRT, ADDRE5S=B, SYNC=YES 

B TERMINAL DEVICE=VIRT, ADDRESS=A, END=YES 

ENQT B 

LOAD $TERMUT1,L0GMSG=N0,END=ENDWAIT 

ENQT A 

The result is a virtual channel between $TERMUT1 and the 
program that loaded it. In Version 1.1 the TERMINAL state- 
ments in the example above will actually generate the fol- 
lowing two lOCB statements? 
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A lOCB A 

B IOCS B 

The lOCB statements that replace the application's TERMI- 
NAL statements must point to TERMINAL statements in the 
system configuration module ($EDXDEF5). Therefore^ for 
this sample to work the following two statements must be 
added to the system configuration module: 

A TERMINAL DEVICE=VIRT, ADDRESS=B,SYNC=YES 

B TERMINAL DEVICE=VIRT, ADDRESS=A, END=YES 

The effect of this change is to increase the size of the 
system area by about 700 bytes and to decrease the size of 
the virtual terminal application by about 6^0 bytes. Since 
multiple programs can share the virtual terminal defi- 
nitions (using ENQT) when they are part of the system con- 
figuration, this may result in an overall decrease in 
storage requirements. However, programs that use the same 
virtual terminal pair can not execute at the same time. 



SENSOR I/O APPLICATIONS 



Applications using the specialized sensor I/O capabili- 
ties of EDX may be affected by changes in timing that 
occur in Version 1.1. The special process interrupt intei — 
face (lODEF SPECPI) is slightly faster than in Version 1.0 
if the application is executed in partition 1 but is esti- 
mated to be 25-30 microseconds slower (on a 4955 process- 
or) if executed in some other partition. Programs with 
extreme time sensitivity should therefore use SPECPI 
TYPE=GROUP and be executed in partition 1. 

The method of return from the SPECPI exit to the supervi- 
sor may also require modification. For SPECPI TYPE=GROUP 
there is no change, but for SPECPI TYPE=BIT a new return 
statement, SPECPIRT, is provided. The Version 1.0 tech- 
nique, which used register 7, is valid only in partition 
1. The new statement* SPECPIRT will work in any partition. 



USE OF ATTENTION LISTS (ATTNLIST) 



Programs that use ATTNLIST exits to provide new commands 
or intercept existing system commands may be affected by a 
change in the method of executing attention routines. In 
Version 1.0 the ATTNLIST routine was executed directly 
from the keyboard task for the terminal in use. In Version 



V 



.^ 



12 Version 1.1 Planning Guide 






1,1» the keyboard task is aluays executed in partition 1 
Mhile the attention exits themselves are executed in what- 
ever partition the exit program resides in. Therefore, the 
keyboard task will ATTACH a special ATTNLIST TCB to 
execute the attention exit. This special TCB is automat- 
ically created when a program containing an ATTNLIST 
statement is assembled, increasing program size by 
approximately 120 bytes. The attention routine is exe- 
cuted in the partition it resides in and therefore does 
not have direct access to the system area. If the atten- 
tion exit needs to reference the system area, refer to the 
section on "References To System Area Data." 



PROGRAM (HEADER) OR TCB DEPENDENCIES 



^^ 



&SYSCOM USAGE 



The PROGRAM header and TCB's that reside within the users' 
application program have changed slightly in size and foi — 
mat. Programs that reference or modify these control 
blocks except for the first two words of a TCB or a DSn 
(DSCB) may require source code modification. While most 
fields have changed only in offset within the data area, 
no assumptions should be made about compatibility. In pai — 
ticular, use of any reserved fields or fields that contain 
address keys indicates that a change would be required. 
IBM recommends against any dependency on these data areas. 



Applications that use a $SYSCOM shared area should not 
require change. However, you may wish to control the 
placement of the $SYSCOM CSECT to minimize the amount of 
storage shared across partitions. All storage locations 
from to the boundary specified in a new SYSTEM statement 
parameter are shared (mapped) by all partitions. There- 
fore it is usually advisable to include the $SYSCOM CSECT 
near the beginning of the supervisor load module rather 
than at the high end. 
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PART 2: EDX MULTIPLE TERMINAL NANAGER 



OVER VI EH 



MULTIPLE TERMINAL MANAGER CONCEPTS 



The Series/1 Multiple Terminal Manager (5719-MSl) is an 
application program that operates under the Series/1 
Event Driven Executive. It provides a set of high-level 
functions that simplify the definition of 
transaction-oriented applications such as inquiry, file 
update, data collection, and order entry. 

Transaction-oriented means that program execution is 
driven by operator actions, typically, responses to 
prompts from the system. 

This prompt-response-process cycle between the program 
and the terminal operator is the basic principle for the 
design of applications using the Multiple Terminal Manag- 
er. 

The Multiple Terminal Manager provides the capability to 
define transactions and manage the programs which support 
those transactions. It also provides management of multi- 
ple terminals as needed to support these transactions and 
their various application programs. The components of the 
Multiple Terminal Manager are' 

• A program/storage manager, which controls the exe- 
cution and flow of the application programs within a 
single program area. 

• A terminal/screen manager, which controls the presen- 
tation of screens and communications between terminals 
and application programs. 

• A file handling mechanism, which simplifies the stoi — 
age and retrieval of data on the bulk storage devices. 

The terminal manager simplifies such transactions by? 

• Automatically providing input and output buffers for 
the application program. 

• Performing I/O operations to access fixed screen foi — 
mats from the screen file. Here, the term screen 
refers to the image that is displayed on the screen of 
an IBM ^979 or IBM 4978 Display Station. Fixed-screen 
formats consist of unmodifiable text and definitions 
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of possible areas for data input. Screens are built 
using the $IMAGE system utility. 

• Returning control to the user program to alloM modifi- 
cation of the input buffer containing the screen if 
desi red. 

• Performing the set of I/O operations involved in writ- 
ing the screen to the terminals filling in unprotected 
fields with user-defined output data, and reading the 
data entered by the operator before returning control 
to the application program that requested the action. 

The terminal manager assumes that each action request , 

involves both output and input operations, thus elimi- 
nating the need for the application program to make 
separate requests. 

In addition, the Multiple Terminal Manager provides stoi — 
age, file, and program management services, terminal 
transaction statistics, the capability for sign-on 
programs for password validation, and error recovery for 
I/O and program check conditions. 

Multiple Terminal Manager applications can be written in 
the Event Driven Language, Series/1 Assembler Language, 
COBOL or FORTRAN IV. Disk I/O can be performed by an appli- 
cation program using indexed or direct access methods. z' \^ 
Terminal support is provided for locally attached IBM <i979 \ jJ 
and '!f978 Display Stations and remote Teletype^ ASR 33/35 
compatible terminals attached using a single-line or 
multiline asynchronous communication adapter. 

The disk I/O function provides the following for disk and 
di skette f i les: 

• Indexed Access Method file support 

• Direct file support 

• Storage conservation through automatic open and close 
functi ons. 

* 
The TERMINAL file describes the terminals to run with the 
terminal manager. In this file, you specify the terminal 

type, the name of the terminal, the screen to be used as * 

the primary menu screen, whether or not sign-on is 
required, and for asynchronous terminals, the length of 
the input buffer. This flexibility allows you to add or 
delete terminals without rebuilding the terminal manager. 
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HARDUARE 



Your appli cation programs can be executed by way of a 
selection from the terminal menu or by a program. Only the 
program name is required. The Multiple Terminal Manager 
performs the operations necessary to load the program and 
control its execution. 

Screen formats are used by application programs and the 
Multiple Terminal Manager itself. Each screen is a data 
set in a volume that defines protected fields and 
optionally defaults for unprotected fields. Three screens 
are predef i ned^ 

• The initial program load (IPL) screen that is dis- 
played Mhen the Multiple Terminal Manager task set 
starts. 

• The sign-on screen (displayed if a sign-on procedure 
is specified for the terminal). 

• A sample primary menu screen for program selection. 
However f you can select any screen as a menu screen. 

These screens are provided as samples and can be modified 
to suit individual requirements. (You can define addi- 
tional screens using the $IMAGE screen build utility). 

The Multiple Terminal Manager responds to an interrupt 
from a terminal by loading the requested program specified 
by program name or program function key selection. The 
terminal manager routes subsequent operator entries to the 
associated program. Two program function keys are 
reserved' 

• PF3 - signals the Multiple Terminal Manager to termi- 
nate the current program and display the menu screen 

• PF6 - signal can still be defined to print the contents 
of the current screen on the system printer. 



The minimum hardware configuration required for the Mul- 
tiple Terminal Manager is as follows' 

• Series/l processor (either ^952 or 4955) with 96KB 
storage 

• Disk storage device (either 4962 or 4963) 

• An Event Driven Executive $SYSLOG device. It is recom- 
mended but not mandatory that this be a non-Multiple 
Terminal Manager terminal for receiving any system 
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messages during the Multiple Terminal Manager exe- 
cuti on. 

• Display station (either 4978 or 4979) 

• Printer - IBM 4973 or IBM 4974 (to define a $SYSPRTR 
for error messages). 

The following optional hardware is supported? 

• Additional 4978 or 4979 terminal devices 

• Teletype^ devices connected to an ACCA adapter 

• Printers as supported by EDX Version 1.1 

• Additional direct access devices (disk or diskette) as 
supported by EDX Version 1.1 

• Additional storage as supported by EDX Version 1.1. 



^, 
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SOFTUARE 



The minimum software requirements for executing the Mul- 
tiple Terminal Manager under EDX are'' 

• EDX Supervisor Version 1.1 (5719-X51) 

• EDX Utilities (5719-UT3). 

• Program Preparation Facilities (5719-XX2)» required 
for program preparation and installation of Multiple 
Terminal Manager applications 

Additional software supported by the Multiple Terminal 
Manager includes^ 

• EDX Indexed Access Method (5719-AM3) if indexed I/O 
will be used 

• EDX FORTRAN (5719-F02) if FORTRAN applications are to 
be executed 

• EDX COBOL (5719-CB3 and 5719-CB^) if COBOL applica- 
tions are to be executed. 






PROGRAM OPERATION 



The Multiple Terminal Manager is invoked using the $L com- 
mand. This will cause the Multiple Terminal Manager pro- 
gram manager to be loaded into storage and activated. The 
first program activated by the program manager is the 
i ni tial i 2ati on routine. 



MULTIPLE TERMINAL MANAGER INITIALIZATION PROGRAM 



This program determines the number of terminals that are 
being controlled and prepares the tables and in-storage 
control blocks to support those terminals. The initial- 
ization routine loads and initializes a terminal server 
for each terminal that i s to be controlled by the Multiple 
Terminal Manager. Uhen initialization is complete^ con- 
trol is returned to the program manager. 
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TERHINAL SERVER PROGRAMS 



The terminal server programs perform all input/output and 
interrupt handling funcjtions for those terminal devices 
operating under the control of the Multiple Terminal Man- 
ager. There is one terminal server program for each termi- 
nal assigned to the Multiple Terminal Manager. 

Uhen a server program is first activated by the initial- 
ization program^ it Mill display a base Multiple Terminal 
Manager message screen and wait for an interrupt from the 
operator. If a sign-on procedure is required for this tei — 
minal/ the server will invoke the sign-on procedure and 
wait until an operator has signed on properly. After pro- 
per sign-on» the server will perform I/O operations as 
needed to satisfy the requirements of operator dialogues 
and the associated application program. The terminal 
servers use ENQ/DEQ and WAIT/POST mechanisms for inter- 
facing with the program manager. 



APPLICATION PROGRAM MANAGER 



The application program manager provides the Multiple 
Terminal Manager program management facilities required 
to satisfy operator requests. The program manager con- 
trols the contents of the program area and the initializa- 
tion of programs within the area. 

The Multiple Terminal Manager is a transaction processing 
subsystem which executes as an application program under 
the Event Driven Executive. The Multiple Terminal Manager 
transactions are initiated by a terminal operator using a 
transaction selection menu (also referred to as a program 
selection menu). Programs can request single or multiple 
operator prompts* process the input* and then request 
additional input or terminate. 

The Multiple Terminal Manager applications are automat- 
ically connected to a terminal when a transaction begins. 
The Multiple Terminal Manager in turn processes terminal 
I/O for the these applications. The applications execute 
within the managed program area, and are provided program* 
terminal* screen and file management services through 
calls to the Multiple Terminal Manager. For example* a 
program executing under control of the Multiple Terminal 
Manager displays a menu screen offering the operator a 
choice of functions. Based on the operator's selection* 
the application program then performs processing opei — 
ations* such as reading information from a data file* dis- 
playing the data at the terminal* and waiting for the next 
response. 
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PROGRAM MANAGEMENT 






The program management facilities provide the capability 
for the control of application programs while performing 
their respective transactional processes within a single 
program area. Because all of the Multiple Terminal Manager 
application programs operate in the same program area» the 
Multiple Terminal Manager program management facilities 
contain the support needed to allow multiplex operation 
and sharing of the program area. 

The application programs using these program/storage man- 
agement facilities will always have the following four 
items associated with them: 

1. The application program itself. This is the usei — writ- 
ten code that performs the transaction processing as 
required by the user. It will reside in the programs 
file and be loaded into the in-storage program area by 
the manager. 

2. The "swap out" data set. This data set is used by the 
manager to save programs and data across calls to 
ACTION, LINK, LINKON, CYCLE, and WRITE. 

3. The input buffer. This buffer contains the data that 
was last entered by the operator when the current seg- 
ment of the application program is entered. This buff- 
er also contains the protected characters of the 
screen display that the application program is prepai — 
ing for the next dialogue with the operator. Refer to 
Figure 4 for additional information. This buffer is 
automatically allocated by the Multiple Terminal Man- 
ager and is 1920 bytes long. 

4. The output buffer. This buffer contains the unpro- 
tected characters of the screen display that the cui — 
rent application program is preparing for the next 
dialogue with the operator. These unprotected charac- 
ters can either be default values or the response to an 
operator query. Refer to Figure 4 for additional 
information. This buffer is automatically allocated by 
the Multiple Terminal Manager and is 1024 bytes long. 

The application programs will interface with these facili- 
ties using the callable functions described in the follow- 
ing paragraphs. 
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ACTION - Fetch Operator Response 



The ACTION function provides the application program with 
the ability to display a screen and then to obtain the 
operator's input to a display on the terminal screen. This 
call function should be preceded by one of the calls to 
format the display buffer. 

When this function is called^ the manager saves the infoi — 
mation needed to return to the next sequential program 
instruction uhen the ACTION function is complete. The man- 
ager then communicates with the operator at the proper 
terminal and constructs the buffer to be returned to the 
calling program. Ulhile the manager is performing this 
operation for the calling program* the storage space con- 
taining the calling program might be placed (by the manag- 
er) with one of the other application programs, thus 
allowing the sharing of the storage resource among several 
application programs. Ulhen the requested ACTION function 
has been completed and the storage has been freed by 
another application program* the manager will reload the 
calling application program and return control to that 
program at its next sequential instruction. Figure 4 shows 
the status of the input and output buffers when this func- 
tion is called. 



LINK - Load and Execute Program 



The LINK function enables an application program to com- 
plete its own execution by loading and executing some oth- 
er application program. Once an application performs a 
CALL LINK, that program will not be returned to from the 
manager, unless the manager detects an error in the call- 
ing sequence to the LINK function; consequently, 
instructions following a CALL LINK must be included to 
handle this problem. Refer to Figure 5 for more informa- 
tion. Also, Figure 4 shows the status of the input and 
output buffers when this function is called. 



LINKON 



The LINKON function is a combination of the functions pro- 
vided by the ACTION and LINK functions; that is, it 
requests &n operator action and, when this action is com- 
plete, loads and executes some other application program. 
Figure 4 shows the status of the input and output buffers 
when this function is called. 
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Figure 4. Buffer contents and usage during control of the 
Multiple Terminal Manager program/ storage manager. 



CYCLE - Suspend Current Terminal Application 



The CYCLE function provides an application program with 
the capability of suspending itself to allow other appli- 
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cations or terminals to become active. After other appli- 
cations have had an opportunity to execute^ the manager 
will reload the calling program and return control to it 
at the next sequential instruction after the call to 
CYCLE. Refer to Figure 4 for more information. 



MENU - Return to Multiple Terminal Manager Control 



The MENU function provides the application programs with 
the capability of aborting their own operation and return- 
ing to the control of the Multiple Terminal Manager base 
program with the operator selection menu displayed on the 
terminal. The operator at a terminal can perform this same 
function with the PF3 key on his terminal. 



MRITE - Output to an Asynchronous Terminal 



The WRITE function is provided for those applications that 
use asynchronous terminals such as the Teletype' ASR 33. 
It causes the specified buffer contents to be displayed on 
the specified terminal. After the display has been written 
on the terminal* the application program must then perform 
a CALL ACTION to receive responses back from the operator. 
This function executes in a similar fashion to the func- 
tions described under "Storage/Program Management" in 
that the application program does not remain in storage 
while the buffer is being written. 



Terminal/Screen Management 



The terminal screen management facilities provide you 
with a simplified method of performing the terminal handl- 
ing functions that your application program may require. 
In addition to providing the means of operating with the 
Series/l keyboard/CRT devices* the terminal/screen manag- 
er also provides facilities for handling asynchronous 
terminal devices. Application programs using keyboard/CRT 
terminals may interface to the terminal/screen management 
facilities through four callable functions, while the 
interfaces with asynchronous terminals will use only one 
callable function. 
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SETPAN - Format the Input and Output Buffers 



The SETPAN function provides the application program with 
the ability to request that a specified screen be 
retrieved from the screens file and loaded into the input 
buffer. The screen images in the screens file will have 
been built using the $IMAGE utility. The contents of this 
input buffer will then be displayed on the next call to 
ACTION, LINK, or LINKON. The screen will be written on the 
terminal display with all positions wri te-protected 
except those in which nulls (X*00*) were defined. 

When this function is called, one of the parameters will 
specify the name of the screen to be retrieved. 



SETCUR - Move Cursor to Specified Position 



The SETCUR function provides the application program with 
the ability to identify the character position at which 
the terminal/screen manager will display the cursor when 
the screen is displayed. 



c 



BEEP - Set Audible Alarm 



The BEEP function provides the application program with 
the ability of activating the audible alarm on the next 
CALL ACTION as a signal to the terminal operator. This 
function is ignored for those terminals that do not have 
an audible alarm capability. 



CHGPAN 



The CHGPAN function is used to notify the terminal manager 
of changes to the number of protected/unprotected charac- 
ters of a screen panel in the input buffer so that the 
terminal manager will know how many unprotected data chai — 
acters to write on the next output cycle. 

Figure 5 i s an example of an application program that pei — 
forms MTM functions to converse with an operator, to allow 
other applications to run, and to link to another applica- 
tion program. 
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ENTRY--> 



^ start 

• 


• 

CALL 

• 


SETPAN (1) 


• 
CALL 


ACTION (2) 


X Process input buffer 

• 


• 

CALL 

• 


CYCLE (3) 


• 
^ Link to new program 


CALL 


LINK (4) 


)i If LINK returns, it 


^ was 


unsuccessful 


^ ERROR HANDLER (5) 


CALL 


MENU (6) 



Figure 5. Sample Application Program 



Read screen image from data set. Protected data goes 
into the input buffer and unprotected data goes into 
the output buffer. 



''X^ 



2. The ACTION function writes protected data from the 
input buffer, and writes unprotected data from the 
output buffer. It then reads operator inputs into the 
input buffer. 

3. The CALL CYCLE suspends the program to allow others to 
execute. 

4. The last call in this application program terminates 
the program and starts the next one. 

5. An error handling routine in the event that the manag- 
er detects ^n error in the calling sequence for the 
LINK function. 

6. The CALL MENU within the error handling routine termi- 
nates the current program and returns to the Multiple 
Terminal Manager with the basic menu displayed. 
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File Management 



The file management facilities provide common^ 
easy-to-use support for all disk data transfer operations 
as needed for the application programs. These facilities 
provide support for both indexed and direct files under 
the control of a single callable function FILEIO (Perform 
Disk I/O) 

The FILEIO function performs read and write operations on 
the disk using either indexed or direct accessing of the 
information. You specify the desired operation to the pro- 
gram using a file control area. This is a callable func- 
tion, and the calling program will remain in storage while 
the operation is taking place. 



FILEIO 






FILEIO provides the facility to access previously created 
files using the call interface described earlier. These 
files must have been previously defined and loaded using 
an offline user-written utility. 



CALL FILEIO, (FCA), (BUFFER), (RETURN CODE) 



Figure 6. FILEIO 



The calling parameters are^ 

• File Control Area (FCA) - Address of a table with the 
parameters describing the requested operations' 

• BUFFER - Address of the user program I/O buffer. This 
is in the user program space. FILEIO and Indexed 
Access Method have their own buffers. 

• RETURN CODE - Address of the 2-byte field to contain 
the return code passed back by FILEIO. This can be a 
FILEIO return code, or it can be passed through from 
the Indexed Access Method. 
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Figure 7. File Control Area 



Indexed File Request Types 



Type Function 

RELS Release from sequential processing mode 

RELR Release from random processing mode 

PUTU Put operation* update mode 

PUTD Put operation* delete mode 

PUTN Put operation* new mode-adds a record to the 
file 

GETD Get operation* direct read 

GETS Get operation* sequential read 

IDEL Delete operation 

ICLS Close an indexed data set 

GTRU Direct get* update mode 

GTSU Sequential get* update mode 
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Direct File Request Jvpes 



Type Function 

READ Read the record defined by the RRN field of the 
FCA into the usei — provided buffer. 

MRU Write the record defined by the RRN field of the 
FCA into the major usei — provided buffer. 

SEOD Set the system-maintained EOD pointer to the 
record number provided in the relative record 
number field of the FCA. 



Multiple Terminal Manager Utilities 






The utility program support consists of operator service 
functions that assist you in the operation of the Multiple 
Terminal Manager system. 

Terminal Activity Report . This report utility enables you 
to display the names and current status of the terminals 
under control of the system. 

Terminal Connection Facilities . Provides the operator 
with the facilities to disconnect and reconnect terminals 
during the normal Multiple Terminal Manager operation. 
These services are performed by the two operator commands* 

• Disconnect - Turn Off Specified Terminals . This facil- 
ity provides the operator with a means of shutting 
down i ndi vi dually-speci f ied» or all terminals* on the 
Multiple Terminal Manager system. If the operator 
requests that a terminal that is currently involved in 
a transaction is to be di sconnected» that terminal 
will be allowed to complete its associated transaction 
before being disconnected. 

• Reconnect - Turn On Specified Terminals . This facility 
provides the operator with a means of restoring a 
disconnected terminal back into operation. 

Programs Report . Prints information about available pro- 
grams. 
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APPLICATION DESIGN INFORMATION 



PROGRAMMING CONSIDERATIONS 



The Multiple Terminal Manager applications are processed 
as initial tasks of a program which execute within the 
program manager's overlay area. On the first execution of 
a program during a transact ion» the program is brought 
into the overlay area by a LOAD. Then, when the program 
returns to the Multiple Terminal Manager through a CALL 
ACTION, WRITE, CYCLE, MENU, LINK or LINKON, the Multiple 
Terminal Manager dequeues the program from the system 
using DETACH. Also, if the program returned using a CALL 
ACTION, WRITE or CYCLE, the Multiple Terminal Manager 
writes the program out to the MTMSTORE data set. The over- 
lay area is then free for use by other programs. When the 
Multiple Terminal Manager is ready to reexecute that pro- 
gram for subsequent processing of the transaction, the 
program manager reads the program into the overlay area 
and requeues that program to the system using ATTACH. 

Thus, the Multiple Terminal Manager transaction programs 
should adhere to the following conventions^ 

• No subtasks should be active across calls to the Mul- 
tiple Terminal Manager 

• No system-wide resources should be enqueued across 
calls to the Multiple Terminal Manager 

• Transaction programs cannot use overlays 

• Transaction programs should be written as main pro- 
grams with the expectation of receiving four parame- 
ters at initiation 

• Transaction programs should use the Multiple Terminal 
Manager for all terminal and disk I/O 

• All other I/O should be complete across calls to the 
Multiple Terminal Manager 

• Transaction programs should terminate only with calls 
to the Multiple Terminal Manager and should not issue 
any PROGSTOP, ENDTASK, or DETACH instructions 

• Error handling routines should terminate with a CALL 
MENU. 
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MULTIPLE TERMINAL MANAGER DATA SET REQUIREMENTS 



MTMSTORE 



.^' 



MTMSTORE, the Multiple Terminal Manager work f i le» con- 
tains! 

• The Multiple Terminal Manager program table 

• The Multiple Terminal Manager screen table 

• A program and buffer save area for each terminal 
defined in the TERMINALS specifications file. 

The size of the MTMSTORE file can be calculated as follows^ 

• AlloN 10 bytes per screen in the SCRNS volume; round up 
to the nearest sector 

• AlloM 12 bytes per program in the PRGRMS volume; round 
up to the nearest sector 

• AlloM per terminal! 

1. Enough sectors to hold a copy of the largest pro- 
gram in the PRGRMS volume 

2. Four additional sectors for full screen devices. 
This data set is in the volume MTMSTR. 



TERMINAL 



This file is built with the $FSEDIT system utility. It 
contains one record/terminal containing the specification 
of a termi nal . 

D V t p , Termname , Menuscrn r Y/N 

Dvtp Type of terminal. Enter? 

4979 IBM '»979 full screen 
4978 IBM 4978 full screen 
3335 ASR 33/35 line at a time 

Termname l- to 8-character name of a terminal. This name 
must be identical with the device name specified 
on the EDX TERMINAL statement at SYSGEN. This 
name should not be the $SYSLOG device. 

Nenuscrn The data set name of the screen to be displayed 
after an operator exits a transaction or signs 
on. For asynchronous terminals, this field is 
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ignored. 

Y/N Y = This terminal is required to use the SIGN-ON 
and SIGNOFF programs. If a user program named 
SIGN-ON does not appear in the program library* 
this terminal is not usable. N = This terminal 
is always signed on. 

Comment records are acceptable in this file as well as com- 
ments following specification records. Comment records 
must have an x in position 1. 

An example of this file would be: 

497 9,DISPLAYl,MENUSCRN,n 
4978,DIS49780,MENUSCRN,y 
3335,ACCAl,MENUSCRN,y 

End of specifications must be indicated with a /x record. 

Before processing each record during task set startup, the 
record is listed on $SYSPRTR. Uhen startup is complete, 
all terminals will have the Multiple Terminal Manager IPL 
screen displayed. The terminal data set is in the volume 
PRGRMS. 



Screen Format Volume - SCRNS 



This volume contains screen panel data sets for full 
screen images built using the $IMAGE system utility. These 
screens must have been built with a 24x80 dimension size. 



User Application Program Volume - PRGRMS 



All programs loaded by the Multiple Terminal Manager are 
loaded using the names of the data sets on this volume. 
The terminal file is also in this volume. 

Application programs are stored in this volume as the out- 
put of the $UPDATE utility. The names of the programs are 
the names used by the operator from the MENU mode to 
invoke programs and can also be used as the program param- 
eter on a CALL LINK from one program segment to another. 

Uhen the Multiple Terminal Manager is initiated, a program 
table is built containing the name of each program data 
set in the PRGRMS volume. 
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Each program is checked to determine if it is too big for 
the program area in the Multiple Terminal Manager. If this 
occurs, the user should split the program into segments 
using LINK or increase the size of the program area. 



Sian-On File - SIGNONFL 



This file contains sign-on records for use by the SIGN-ON 
program. The format of the file is? 



Field Name 


Posi ti ons 


Contents 


EMPLOYEE 


1-08 


Employee number 


PASSWORD 


9-12 


Password 


USERID 


13-16 


User ID 


USER CLASS 


17-20 


User class 


NAME 


21-32 


Employee name 



This file is built by using the $FSEDIT EDX utility. This 
file is in the volume PRGRMS. A /^ in columns 1 and 2 
denote the end of the file. 






OPERATOR INTERFACE 



Multiple Terminal Manager Initialization 



The Multiple Terminal Manager can be initiated from any 
terminal defined to the system by entering the $L 
$MTM»PRGRMS command. The $L $MTM command will cause the 
Multiple Terminal Manager program manager to be initi- 
ated. The program manager will then initiate a terminal 
server for each terminal specified in the TERMINAL file. 
Upon completion of initiation, the IPL screen, IPLSCRN, 
will be displayed at each of the Multiple Terminal Manager 
terminals. IPLSCRN will specify that the operator press 
the enter key in order to display either the sign-on or 
menu screen. 

The data set IPLSCRN is displayed on each full screen tei — 
minal after the Multiple Terminal Manager is started. It 
requests that the operator press the enter key to connect 
the terminal to the Multiple Terminal Manager. It should 
not be displayed again. 
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For execution 



VOL ID Data set name 



Size 



Swap data set 
Program manager 
4978/4979 term server 
TTY term server 
MTM initialization 
Terminal specifications 

User application pgms 



Screen formats 

Sign-on file 

For program preparation 

MTM stub 

MTM auto call list 



MTMSTR MTMSTORE See MTM data set reqm'ts 

PRGRMS CDMPGMGR 36 Sectors 

PRGRM5 CDMFLSCR 6 Sectors 

PRGRMS CDMTTY 6 Sectors 

PRGRMS CDMINIT 22 Sectors 

PRGRMS TERMINAL 4 Sectors 

(appx) 

PRGRMS (User specified) ? 



SCRNS (User specified) 4 Sectors 

SCREENS Per screen 

PRGRMS SIGNONFL 4 Sectors 

(appx) 



(User specified) 
(User specified) 



8 Sectors 
2 Sectors 



For rebuilding MTM 
MTM Source 



(User specified) 



2500 Sectors 



Note: MTMSTR, PRGRMS, SCRNS must be defined at SYSGEN time as 

logical volumes. 

This may necessitate a remapping of the disk on which they will reside. 



'^. 



J 



Figure 8. Summary of Multiple Terminal Manager Data Set Requirements, 



SIGN-ON 



If sign-on was specified for the terminal, then the 
sign-on screen, sign-on, will be displayed following the 
IPL screen. The sign-on screen will require that the opei — 
ator enter a usei — id and password. After sign-on process- 
ing has been completed, then the menu screen will be dis- 
played. 



PR06RAH INITIATION AND TERMINATION 



After the Multiple Terminal Manager initiation and 
sign-on processing have been completed, then the menu 
screen is displayed. The menu screen is the screen from 
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which the operator can initiate transactions. A trans- 
action is initiated by the operator entering either a pro- 
gram name or pressing a PF key when the menu screen is 
displayed. A PF key will initiate program PFOn where n 
reflects the number of the PF key pressed. If data is 
entered, the Multiple Terminal Manager will consider the 
first eight bytes to be a program name. 



DISCONNECT 



RECONNECT 






After a transaction is initiated, the operator can termi- 
nate it by pressing the PF3 key. Upon termination of the 
transaction, the menu screen will be redisplayed. Subse- 
quently pressing the PF3 key from the menu screen will 
cause the sign-on screen to be redisplayed if sign-on was 
specified for that terminal. Otherwise, PF3 will be a 
no-op and the menu screen will remain displayed. 



Terminals can be disconnected from the Multiple Terminal 
Manager or the Multiple Terminal Manager can be terminated 
via the DISCONNECT facility. DISCONNECT is invoked from 
the menu screen by keying in either DISCONNECT, termname or 
DISCONNECT, ALL . If a referenced terminal is in a trans- 
action, that transaction is allowed to complete. When the 
terminal returns to MENU state, it is automatically signed 
off and displays the YOU ARE DISCONNECTED message. Termi- 
nals in MENU state are signed off immediately. 

If ALL is specified, all terminals are disconnected. Ulhen 
the last terminal is truly disconnected, whether using ALL 
or separate disconnects, the manager task is stopped. 

To enter this command from a menu screen, the screen must 
contain at least nineteen unprotected characters. 

Uhile a terminal continues in a transaction with discon- 
nect pending, the audible alarm is sounded after every 
interaction to tell the operator that a disconnect is 
pendi ng. 



If the referenced terminal is disconnected, it is recon- 
nected in a signed-off status if applicable. If it is not 
disconnected, the command is ignored. 
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PR06RANS REPORT 



This report displays data from the program table about 
each available program. It is intended mainly for debug- 
ging during development of the manager but is included as 
a Morking example for possible use. 

The program name for this program is PGMRPT. 



TERMINAL ACTIVITY REPORT 



This program displays the names and status of all termi- 
nals on the system. If more than 22 terminals are 
attached^ the operator must press ENTER to page to succes- 
sive groups of 22 lines. 

The program name for this program is REPORT. 



SCREEN PRINT 



Terminal displays can be printed on the system printer 
using the PF6 key to invoke the system's print screen 
facility. EDX print screen facility. This entails press- 
ing the PF6 key. 



DISTRIBUTION AND INSTALLATION 



The Multiple Terminal Manager Mill be distributed as a 
licensed program and Mill consist of the folloMing items: 

• Prebuilt Multiple Terminal Manager - This Mill be a 
ready to load program consisting of a program manager, 
file manager/ terminal servers and sample programs. 

• Multiple Terminal Manager source - This Mill be the 
complete set of the Multiple Terminal Manager source 
code for the user Mho Mants to tailor his Multiple Te» — 
minal Manager environment. 

• Application Stub - This Mill be the Multiple Terminal 
Manager stub in object format that the user must 
include Mith his application programs at link time. 
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• Application Stub AUTOCALL List - This is the auto list 
that the user Mill use at link time to cause the appli- 
cation stub to be appended to his program. 

• Screen Formats - This will be a set of screens to sup- 
port the default Multiple Terminal Manager and sample 
programs. 

• Terminal File - This Nill be a set of miscellaneous 
terminal statements to support the default system. 

The user must create the follouiing volumes on his system 
disk: 

• PRGRMS - This volume is for the Multiple Terminal Man- 
ager programs, user application programs and the tei — 
minal specifications file. 

• SCRNS - This volume is for the screen formats used by 
the Multiple Terminal Manager and user applications. 

• MTMSTR - Contains only the MTMSTORE data set. This the 
Multiple Terminal Manager swap file. 

After the volumes have been created, the user can then copy 
the prebuilt Multiple Terminal Manager, screen formats and 
terminal file from the shipped diskettes to disk. This 
will install the default Multiple Terminal Manager and 
establish the following data sets. 

Data sets within the PRGRMS Volume*. 

CDMPGMGR Multiple Terminal Manager program manager 

CDMSVR89 Multiple Terminal Manager full screen, 4978 and 
4979, terminal server 

CDi1SVR33 Multiple Terminal Manager TTY terminal server 

CDNINIT Multiple Terminal Manager initialization 
routi ne 

TERMINAL Multiple Terminal Manager terminal 
specification file 

Other Miscellaneous data sets needed for the sample 
programs 

Data sets within the SCRNS Volume: 

IPLSCRN The initial Multiple Terminal Manager started 
screen 

SIGN-ON The sign-on screen 
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NENUSCRN The default menu screen 

Other Miscellaneous screen data sets needed for the 
sample programs 

If the user wants to tailor his Multiple Terminal Manager, 
then he can re-assemble, re-build and replace the changed 
Multiple Terminal Manager components. 

The user can then modify his terminal specifications file 
to match his system environment by using the $FSEDIT sys- 
tem utility. He can also add screen formats to the SCRNS 
volume using the $IMAGE system utility. 

Before executing the Multiple Terminal Manager, the user 
has to create the MTMSTORE data set; refer to Figure 8 for 
the MTMSTORE requirements. 



PROGRAM PREPARATION 



During program preparation, the user must ensure that the 
link phase includes the Multiple Terminal Manager shipped 
AUTOCALL list and application stub in order to resolve 
CALLs to the Multiple Terminal Manager function routines. 

After linking his application programs with the Multiple 
Terminal Manager application stub, the user then must 
store the prepared program in the PRGRMS volume using $UP- 
DATE. 



PERFORMANCE INFORMATION 



The information shown in Figure 9 may be used for perform- 
ance planning purposes. The basis for the information is 
from modelling the Multiple Terminal Manager system. 
lAihile the modelling results provide some general guide- 
lines as to the performance of the system, it should be 
noted that the models are only partially validated for the 
workloads modelled. Other workload assumptions may pro- 
vide a different set of performance results. 

As a general guideline to Multiple Terminal Manager per- 
formance, the mean expected response time should be less 
than or equal to 3 seconds with 1 to 4 terminals. The per- 
formance may exceed this range. Mean expected response 
time is the average response time experienced from when 
the user presses the enter key until the first character 
of the response is displayed. 
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Figure 9. Multiple Terminal Manager Performance Trends 



Figure 9 shoNs the response time results for each of the 
transactions. The highest set of response times was 
achieved under a complex file update transaction and the 
lowest was with a non-Indexed Access Method simple file 
inquiry. With all these cases the response time was under 
2 seconds. 

A key variable to response time results is the think plus 
key-in-time associated with a set of terminals. Ulhen this 
variable is very short* the system resources may be 
stressed and can result in higher response times. Uhen 
this variable is increased* the mean response time will be 
smaller. 

Refer to Figure 10 for a definition of the transactions 
used in the model. The think mean plus key-in-time for the 
modelling was 20 seconds. 
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Program 
Type size 


JAM 
Database 


Number of 
disk I/O 


Simple 


22K 


GETD 




4 


inqui ry 










Simple file 
inqui ry/ 
update 


22K 


GETD, 
PUTU 




5 


Simple file 


15. 6K 


- 




2 


inqui ry 
(non-IAM) 










Complex file 48K 
update 


GETD, 
GETD, 
PUTU 




10 



Number of application 
instructions executed 

27. 8K 



28. 7K 



15. 6K 



41. 9K 



Figure 10. Transaction Description 



The folloMing Mere the modelling assumptions: 

• Configuration 

-4955 (translated) 
-4963 (1 unit) 
-4978 display terminals 
-Adequate storage 
-Indexed Access Method 

• Workload 

-Transaction rate of 3 per minute p^r terminal 
-20 seconds (exponential) think plus key-in-time 
-COBOL and Indexed Access Method application 
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PART 3: EDX INDEXED ACCESS METHOD 



OVERVIEU 



The Indexed Access Method Licensed Program (5719-AM3) is a 
data management system that operates under the IBM 
Series/1 Event Driven Executive. It provides you with an 
Event Driven Language callable interface to build and 
maintain an indexed data set and to access^ by key or 
sequentially^ your records in that data set. In an indexed 
data set» each of your records is identified by the 
contents of a predefined field called a key. The Indexed 
Access Method builds into the data set an index of keys 
that provides fast access to your records. 



INDEXED DATA SET FEATURES 






For your applications using indexed data setSf the Indexed 
Access Method offers several useful features? 

• Direct and sequential processing. Multiple levels of 
indexing are used for direct access* and sequence 
chaining of data blocks is used for sequential access. 

• Support for high insert and delete activity without 
significant performance degradation. Free space is 
distributed throughout the data set and in a free pool 
at the end so that inserts can be made in place; space 
provided by deletes can be immediately reclaimed. 

• Access to a single data set by several requests con- 
currently. These requests can execute from the same or 
different programs. Data integrity is maintained by a 
file-» block-, and record-level locking system that 
prevents access to that portion of the file that is 
bei ng modi f i ed. 

• Implementation as a separate task. A single copy of 
the Indexed Access Method executes and coordinates all 
requests. The buffer pool supports all requests and 
optimizes the space required for physical I/O; in the 
user program the only buffer required is the one for 
the record currently being processed. 

• An Indexed Access Method utility program ($IAMUT1) 
which executes as a user program, and allows you to 
create, format, load, unload, and reorganize an 
indexed data set. 
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DATA PROTECTION 



The Indexed Access Method performs all input/output bpei — 
ations by using system functions. Therefore* all data pro- 
tection facilities offered by the system also apply to the 
indexed data sets. The following additional data pro- 
tection is provided by the Indexed Access Method^ 

• Exclusivity option. As a user of the Indexed Access 
Method* you specify on the PROCESS or LOAD request 
that the data set is for use exclusively. This allows 
you to impose additional control where needed. 

• Record locking. The Indexed Access Method automat- 
ically prevents two users from using the same data 
record at the same time. 

• Immediate write-back. This optional feature provides 
the capability of having all updated records written 
immediately to the data set. 

• Accidental key modification. If you attempt to modify 
the key field in one of your data records* the Indexed 
Access Method prevents the modification from occui — 
ring. This helps ensure that your index and data 
match. 



DEVICES SUPPORTED 



The Indexed Access Method supports indexed data sets on 
these direct-access devices* 

• IBM 4962 Disk Storage Unit 

• IBM 4963 Disk Subsystem 

• IBM 4964 Diskette Storage Unit 

• IBM 4966 Diskette Magazine Unit 



o 
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COMPONENTS 



The Indexed Access Method consists of the following compo- 
nents' 

• A load module that supports the execution of your 
programs* which contain the Indexed Access Method 
requests. Indexed Access Method functions are initi- 
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FUNCTIONS 









ated by your programs through a CALL interface. 

A set of object modules that you may use to generate a 
customized Indexed Access Method load module (a read 
only system, for example). If you use the supplied 
load module, you do not need the object modules. 

An object module, called a link module , which you 
include with your program to provide the interface to 
the Indexed Access Method. This link module is some- 
times called a stub . 

A set of copy code modules. You can reference these 
modules from your programs to define symbolic labels 
used in Indexed Access Method requests. 

A load module for the Indexed Access Method utility 
program. 



You request the services of the Indexed Access Method 
through a call interface. 

(CALL IAM,+FUNC,IACB,(PARM3),(PARM4),+PARM5). 

The following functions can be invoked^ 

PROCESS Builds an indexed access control block (lACB) 
and connects it to an indexed data set for read- 
ing, updating, inserting, and deleting records. 
You can then use the lACB to issue requests to 
that data set. A program can issue multiple 
PROCESS functions and obtain multiple lACBs for 
the same data set so that the data set can be 
accessed by several requests concurrently. 

LOAD Similar to PROCESS but allows loading or 
extending the initial collection of records. 

GET Directly retrieves a single record from the data 
set. If you specify the update mode, the record 
is locked (made unavailable to other requests) 
and held for possible modification or deletion. 

GETSEQ Sequentially retrieves a single record from the 
data set. If you specify the update mode, the 
record is locked (made unavailable to other 
requests) and held for possible modification or 
deleti on. 
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PUT Loads or inserts a neM record depending on hoM 
the data set was connected J LOAD or PROCESS. 

PUTUP Replaces a record that is being held for update. 

PUTDEL Deletes a record that is being held for update. 

RELEASE Releases a record that is being held for update. 

DELETE Deletes a single record, identified by its key, 

from the data set. ' 

ENDSEQ Terminates sequential processing. ^ 

EXTRACT Provides information about the file (file 
control block) . 

DISCONN Disconnects an lACB from an indexed data set, 
thereby releasing anv locks held by that lACB, 
writing out all buffers associated with the data 
set, and releasing the storage used by the lACB. 

These functions provide you the support necessary to build 

an indexed data set and to perform direct or sequential 

processing on that data set. Routines using these services 

are written in Event Driven Language and can be included in 

programs written in any language that supports the calling /TA 

of Event Driven Language routines. L J 

In addition, the Indexed Access Method utility program 
($IAriUTl) provides a set of commands which help you manage 
your indexed data sets. The following commands are pro- 
vided by the Indexed Access Method utility program^ 

CR The create function allows you to allocate space 
for your data set in a volume by internally 
invoking the $DISKUT1 system utility. When the 
create command is entered on a terminal, the 
$DISKUT1 program i s loaded and you can then use 
the AL command of $DISKUT1 to allocate a data 
set; any other $DISKUT1 function can also be 
performed. Communication to the $DISKUT1 utility 
continues until the end command (EN) is entered, 
at which time communication to the Indexed 
Access Method utility program is restored. 
Information on the $DISKUT1 utility can be found 
in the Utilities, Operator Commands and Program 
Preparati on manual. 

DF The def i ne command of the Indexed Access Method 
utility program uses an existing data set and 
usei — specified information to define an indexed 
file, when the define command is entered, you 
are prompted for the immediate write-back option 
and for the volume and data set names of the data 
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set to be formatted. The define function per- 
forms size calculations and formats the data 
set. The size calculation information is 
returned to your terminal at the completion of 
the define function. Prior to entering the 
define commands you must use the SE command to 
set up parameters that determine the size and 
format of the indexed data set. 

DI The di splav command alloMS you to display the 
current saved values for the define commands as 
described above. 

EC The echo command alloMs you to set or reset echo 
mode. Ulhen echo mode is on, the input and output 
of the current utility session is logged on the 
$SYSPRTR device. Echo mode remains on until 
either the current utility session is ended or 
it is reset by the EC command. Ulhen the Indexed 
Access Method utility is loaded/ echo mode is 
initially off. Note: Output from the $DISKUT1 
program will not be logged since the terminal 
input/output is handled directly by the $DISKLIT1 
utility (not $IAMUT1). 

EN The end command ends the current utility 
session. 

LO The load command loads an indexed data set from 
a sequential data set. 

RO The reorgani ze command loads an empty indexed 
data set from an existing indexed data set. 

SE The setparms command prompts you for parameters 
that determine the structure and size of the 
indexed data set, and sets these values in a 
parameter list. Size calculations bvg performed 
using the parameters you specify and are 
returned to your terminal. The setparms command 
should be entered prior to using the define 
command to do the actual data set formatting. 
All values that you specify for parameters of 
the setparms command are saved (until the end of 
the session) for later invocations of the 
setparms command and the define command. You can 
display these values by entering the DI command. 

UN The unload command unloads an indexed data set 
to a sequential data set. 

For each of these utility functions, you are prompted for 
the volume and data set names of the input and/or output 
data sets. 
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INDEXED DATA SETS 
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You can organize a collection of data into an indexed data 
set if the data consists of fixed-length records and each 
record is uniquely identified by the contents of a single 
predefined field. This identifier is called the key. 
Records are arranged in an indexed data set in ascending 
order by key. Some reserved space can be distributed 
throughout the data set so that records can be inserted in 
their key position during processing. This space is called 
free space . 

+ 

The Indexed Access Method puts records into an indexed 
data set in either of two ways' 

1. In LOAD mode* records are presented in ascending order 
by key and are loaded into the data set sequentially^ 
skipping any free space. These records are called the 
base records . Each record loaded must have a new high 
key; that is» it must have a key higher than any key 
already in the data set. 

2. In PROCESS mode, records are inserted in their proper 
key position relative to records already in the data 
set. Records can be inserted using the free space 

skipped during loading or, if a record has a new high /^ ^x 

key, in the unused space after the last loaded record. W ir 

You connect an indexed data set to your application 
program with the LOAD or PROCESS request. 

The total number of base records that can be loaded is set 
using the define command of the Indexed Access Method 
utility program when the indexed data set is built. It is 
not necessary, however, to load all the base records 
before processing can begin. The data set can be connected 
for loading some of the base records, connected for proc- 
essing including inserts, and later connected for loading 
more base records. Figure 11 illustrates this sequence. 

The total amount of free space for inserts is specified by 
the define command of the Indexed Access Method utility 
program when the indexed data set is built. This free space 
is distributed throughout the data set in the form of free 
records in each data block, free blocks in each block 
grouping, and/or in a free pool at the end of the data set. 

An indexed data set contains space allocated for base 
records and insertions and for a multilevel index and the 
control information required to use the index and the free 
space. This type of information is useful for planning, 
diagnostics, and a general understanding of the Indexed 
Access Method. See "Data Set Format" on page 70 for a 
description of the format of the indexed data set. 
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Figure 11. Loading and Inserting Records in an Indexed Data Set 



PROGRAH OPERATION 



The Indexed Access Method comprises of a load module and a 
link module. The link module is included in a user's pro- 
gram at link-edit time as an autocall module. The Indexed 
Access Method performs I/O operations using standard data 
management requests. 

The Indexed Access Method operates under Version 1.1 of 
the Event Driven Executive. 



A single copy of the Indexed Access Method serves the 
entire system. The Indexed Access Method can be loaded 
automatically at IPL time through the $INITIAL feature of 
the system* or it can be loaded manually by using the $L 
(load) command. The Indexed Access Method does not need to 
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be loaded before it is used by any program. The name of 
the Indexed Access Method for loading purposes is $IAM. 
Once loadedf the Indexed Access Method remains in storage 
until cancelled. 

The Indexed Access Method can be loaded into any address 
space/ including address space zero. It can be invoked 
(through the link module) from any address spacer includ- 
ing the address space it is in. Figure 12 shouis an example 
of a system containing the Indexed Access Method. 



Address space 



Appli cati on 
program 



link 



Control blocks 
and buffer pool 

Indexed 

Access 

Method 



Event 

Driven 

Executi ve 



Address space 1 



Address space 2 



Applicati on 
program 



link 



Appli cati on 
program 



link 



Applicati on 
program 



link 



Each application program contains a copy of the link module* 
which provides the interface to the single copy of the 
Indexed Access Method. 

Figure 12. Example System Environment 



w 



APPLICATION PROGRAM PREPARATION 



Application programs that issue Indexed Access Method 
requests are prepared as follows: 
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1. Programs are assembled by any of these assemblers^ 

• The EDX assembler, $EDXASM, from the EDX Program 
Preparation Facility (5798-XX2). 

• The EDX macro assembler $S1ASM (5719-AMA) 

• The Series/1 macro assembler supplied by the Sys- 
tem/370 Program Preparation Facility for the 
Series/1 (5798-NNQ). 

2. Use the linkage editor, $LINK» to combine object mod- 
ules produced by any of the above assemblers, along 
with the IBM-supplied link object module, into a sin- 
gle module. 

3. Use the conversion program, $UPDATE or $UPDATEH, to 
convert your module into loadable form. 



APPLICATION DESIGN INFORMATION 






This chapter provides guidelines for designing applica- 
tions that use the Indexed Access Method. It describes: 

• Preparing and maintaining data 

• Designing an indexed data set 

• Using the functions provided 



PREPARING THE DATA 



The following sections describe how you can design an 
indexed data set that uses space efficiently and provides 
optimum performance. 



Defining the Key 



Define a single key field for each indexed data set by 
specifying its sSzg and position in the record when the 
data set is built by the define command of the Indexed 
Access Method utility program. The longer the key, the 
larger the index contained in the indexed data set. There- 
fore the key should not be longer than necessary. However, 
the key must be long enough to ensure uniqueness. 
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Ensuring Uniqueness of the Key. In order to identify each 
record in an indexed data set, each key must be unique. If 
key duplication is possible, the key field should be 
expanded. 

Customer name is a good example of a key with which dupli- 
cations can occur. One way to avoid duplication is to 
lengthen the key field to include other characters such as 
part of the customer address or the account number. Since 
the characters in the key must be contiguous, this sol- 
ution can involve rearranging the fields in the record. 

Another way to eliminate duplication is to modify new 
records dynamically whenever a duplication occurs during 
loading or processing. A position at the end of the key 
field can be reserved for a suffix code. Whenever a dupli- 
cate occurs, you can add a value to the suffix and make 
another attempt to add the record to the data set. The 
result can be a data set that contains a sequence of keys 
such as Smith, Smith 1, Smith 2, and so forth. If you add a 
suffix, you must use the entire unique key to access a 
specific record. 

Providing Access by More Than One Key. To provide good 
performance with both direct and sequential access, each 
indexed data set is indexed by a single key. At times, 
however, it may be useful to locate records by a secondary 
key. For example, in a customer file indexed by account 
number, you might want to locate a record by customer 
name. 

One way of providing access by a secondary key is to build 
a second indexed data set composed of short records that 
contain only the secondary and primary keys. Using the 
secondary key to access this data set, the associated 
primary key can be determined. The primary key can then be 
used to locate the desired record in the first data set. 

Uhere there are multiple keys to a data set, ensure high 
performance by selecting as primary key the one that is 
used most often or the one with which you plan to do 
sequential processing. 



Selecting the Block Size 



Records can be blocked in an indexed data set. The block 
size must be a multiple of 256. Blocking reduces I/O 
activity; it also allows for free records to be intei — 
spersed among base records to provide space for inserts. 
Free records are one kind of free space; free blocks 
included at the end of each block grouping, or at the end 
of the data set, are others. 
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Specify record size and block size Nhen building the data 
set by the setparms command of the Indexed Access Method 
utility program. Each block has a 16-byte header. There- 
fore, the number of records per block is? 

(block size - 16) 
record size 

The result is truncated; that is, any remainder is 
dropped. A remainder represents the number of unused bytes 
in the block. Selection of a block size is largely depen- 
dent on record size, but the block size must be a multiple 
of 256. Other factors to consider are insert activity and 
buffer space. 

Insert Activity. Each block contains allocated record 
areas into which base records can be loaded and can con- 
tain free record areas into which records can be inserted 
during processing. The ratio of allocated records to free 
records in a block should be close to the ratio of esti- 
mated base records to estimated inserts in the data set. 
Ideally, block size should be large enough to accommodate 
enough records to approximate this ratio. 

Buffer Space. A large block size is advantageous in that 
it minimizes the read/write activity, but it is costly in 
terms of the read/write buffer space required from the 
buffer pool. Some processing requires a buffer large 
enough for two blocks. 

Examples. A data set consists of 1000 base records with an 
estimate of 500 records to be inserted and a record size 
of 70 bytes. Select a block size and a number of free 
records per block to build an indexed data set. 

1. Selecting a block size of 256 with 1 free record per 
block implies (256-16)/70 = 3 records per block, with 
a remainder of 30 bytes. The ratio of 2 allocated 
records and 1 free record accurately reflects the 
insert activity. Buffer size is minimized. Some space 
is wasted on the disk (30 bytes per sector). Designing 
80-byte records and 256-byte blocks for thi s data set 
effectively uses these 30 bytes. 

2. Selecting a block size of 512 with 2 free records per 
block implies (512-16)/70 = 7 records per block, with 
a remainder of 6 bytes. The ratio of 5 allocated 
records to 2 free records underestimates the insert 
activity. The larger block size requires a larger 
buffer but increases I/O efficiency. Fewer bytes are 
wasted on the disk (6 bytes in 2 sectors). 
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Estimating Free Space 



Specify free space for inserts using the setparms command 
of the Indexed Access Method utility program. 

An exact calculation to estimate free space is not neces- 
sary. Experience can be your best guide; if the need for 
file reorganization is signalled (no space for an insert) 
before a major portion of the free space is utilized, you 
knoM you must adjust the mix of free records and free 
blocks, reserve blocks, and reserve index blocks. 

As a general approach, estimate not only the number of 
inserts but also their distribution throughout the data 
set. For example, consider a data set with 5 records per 
block, and 10 data blocks per cluster.* Suppose that the 
data set consists of 300 base records and 200 inserts. 

If the inserts &re distributed evenly throughout the data 
set, the pattern of inserts \3' 



Blocks 



Inserts 



With this kind of distribution you can specify 2 free 
records per block to absorb the inserts; no free blocks 
are needed. 

Of course inserts do not usually occur in such an even 
pattern. Free blocks help to absorb a concentration of 
inserts. The more uneven the expected distribution, the 
greater the free block specification should be. 

Suppose the same number of inserts are distributed in this 
pattern J 



Blocks 



Inserts •••• • ••• 



• • ••• 



With this distribution you must specify either 3 free 
records per block, or 20% free blocks with 2 free records 
per block. 

Now suppose the distribution were more uneven J 



A cluster is a group of blocks; the extent of the group being detei — 
mined by the structure of the index. This is more fully described in 
"Data Set Format" on page 70. 
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In this case a satisfactory mix of free space is 1 free 
record per block and 40% free blocks. 

If the anticipated insert activity is confined to only a 
few clusters^ it is better to use a free pool. A free pool 
is a group of blocks* at the end of an indexed data set» 
that are available to be used wherever they are needed 
within the file. However* in order to use blocks from the 
free pool* the data set must be structured so that they 
can be logically connected where they are needed. This 
structure is specified with the RSVBLK and RSVIX parame- 
ters of the define command of the Indexed Access Method 
uti li ty program. 

Use the RSVBLK parameter to indicate the percentage by 
which a cluster can grow* by taking data blocks from the 
free pool. The structuring is accomplished by leaving 
reserve entries in the lowest level index blocks. These 
reserve entries are not originally used* but can be used 
later to point to data blocks taken from the free pool. 

Use the RSVIX parameter to indicate the percentage by 
which a cluster grouping can grow by adding new clusters. 
This structuring is accomplished by leaving reserve 
entries in the second-level index blocks. These reserve 
entries are not originally used* but can be used later to 
point to new lowest-level index blocks taken from the free 
pool. This lowest-level index block is the seed for a new 
cluster and can ultimately grow into a full-sized cluster 
as data blocks are taken from the free pool. 

As an example of the advantage of a free pool* assume that 
a data set contains 50 clusters of 10 data blocks each and 
40% of the blocks in the cluster ar& free blocks. There 
are 200 free blocks in the data set. If most of the 
inserts into the data set will fall into a relatively 
small key range and do not normally require more than 50 
blocks* 150 blocks are saved by specifying no free blocks 
and a 40% RSVBLK. 

A 25% FPOOL parameter provides the 50 blocks in the free 
pool to be used where the inserts are required. The result 
is that the data set still accepts all the anticipated 
inserts and 150 blocks are saved. 
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If insert activity into the data set is anticipated to be 
relatively even» the space for inserts should be reserved 
as free records and free blocks. This results in the best 
response time from the Indexed Access Method. 

If, however, insert activity into the data set is to be 
primarily into one or more areas or key ranges, the space 
for inserts should be reserved as reserve blocks and/or 
reserve indexes. This results in the most efficient use of 
space in the data set. 

The space for inserts can be divided between free records, 
free blocks, reserve blocks, and reserve indexes to suit 
your requirements. 

To determine how many blocks are required for an indexed 
data set with a given combination of free records, free 
blocks, reserve blocks, reserve index blocks, and free 
pool size, use the SE command of the Indexed Access Method 
utility program (see "Determining Size and Format"). 



BUILDING THE INDEXED DATA SET 



The SE and DF commands of the Indexed Access Method utili- 
ty program allow you to specify the size and format of 
your indexed data set and to do the actual data set 
formatting. Use the SE command to enter those values that 
determine the size of the indexed data set and to receive 
size calculation information. Use the DF command to cause 
the actual data set formatting to occur, using the values 
previously specified on the SE command. 



Determining Size and Format 



The design of the data set is determined by these parame- 
ters of the SE command^ 

BLKSIZE - Block size 

RECSIZE - Record size 

KEYSIZE - Key size 

BASEREC - Estimated number of base records 

FREEREC - Number of free records per block 

FREEBLK - Percentage of free blocks 
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• RSVBLK - Percentage of reserved data blocks 

• RSVIX - Percentage of reserved primary index blocks 

• FPOOL - Percentage of free pool 

• DELTHR - Percentage delete threshold 

The define (DF) command fixes the size of the data set. 
Therefore, BASEREC, FREEREC, FREEBLK, RSVBLK, RSVIX, and 
FPOOL should be large enough to accommodate the maximum 
number of records planned for the data set. To calculate 
the size of the data set for a given combination of the 
define parameters, use the SE command. 

The DF command alloujs you to select the immediate write- 
back option. With this option you can cause modifications 
to the indexed data set to be written to the file imme- 
diately. This contributes to the integrity of the file, 
but increases response time. 



Defining and Creating the Indexed Data Set 






The setparms (SE) command allows you to receive the size 
calculation information without actually performing the 
data set formatting. The size of the data set and other 
relevant information are returned to your terminal by the 
utility. The calculations performed by the setparms func- 
tion are described in "Data Set Format" on page 70 and are 
summarized in "Summary of Calculations" on page 84. Use 
the DF command to actually format the data set. You are 
prompted for the volume and data set names, and for the 
immediate write-back option, of the data set to be format- 
ted. (Notes the data set must be previously created using 
the CR command of the Indexed Access Method utility pro- 
gram and/or the AL command of the $DISKUT1 utility.) This 
data set is connected and then formatted by the define 
function. If the data set does not contain sufficient 
space to support the specified format, the amount of space 
required is returned to you. Knowing the available space 
and using the SE command, you can vary the define parame- 
ters to design a data set that fits. If the specified data 
set does not exist, a connect error will occur and you are 
given the option to retry. If you indicate to retry, you 
are prompted for the volume and data set names of the data 
set to be formatted and the function is attempted again. 
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Connect I nei and Disconnecting the Indexed Data Set 



Uhen you prepare to use an indexed file by the Indexed 
Access Method* you must issue a LOAD or PROCESS request to 
connect it to your program. 

A LOAD or PROCESS builds an indexed access control block 
(lACB) that is associated with an indexed data set. The 
I ACB connects a request to the data set. 

Only one LOAD can be connected to the data set. However » 
processing can take place concurrently with loading. No 
LOAD or PROCESS is successful until the file has been for- 
matted using the define command of the Indexed Access 
Method utility program. 

Multiple lACBs can be associated with the same data set. 
Data integrity is maintained by a locking system that 
allocates file* record* or block locks to the requesting 
lACB in order to prevent concurrent modification of index 
or data records by other requests. 

An lACB can hold only one lock at a time; therefore* if 
your application requires concurrent execution of func- 
tions that obtain locks (direct update or sequential 
update - see "Processing" on page 59 for a description of 
these functions)* you must issue multiple PROCESSes to 
provide multiple lACBs. The Indexed Access Method retains 
information about these requests in the lACB. 

A DISCONN disconnects an lACB from the data set* releases 
the storage for that lACB* releases locked blocks or 
records being held by that lACB* and writes out blocks to 
the data set that are being held in the buffer. The 
DISCONN request can be made any time during loading or 
processing. 

There is no automatic DISCONN on task termination. It is 
very important that you disconnect your indexed data sets 
prior to terminating your task* failing to do so may pre- 
vent resources allocated to your task from being allocated 
to other tasks and updates from being written back from 
the buffer to your data set. 



LOADING BASE RECORDS 



Base records must be loaded in ascending order by key. 
Initiate loading of base records with a LOAD request. Then 
load the records with a PUT for each record. Ulhen the 
desired number of records has been loaded* issue a DISCONN 
request to terminate the load procedure. The only valid 
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PROCESSING 






requests that can follou a LOAD request are* 

• PUT 

• EXTRACT 

• DISCONN 

You need not load all the base records at once. A data set 
that contains some records can be reconnected for loading 
more records. The key of each new record must be higher 
than any key already in the data set. 

AlsOf the limit on base records as specified on the define 
command of the Indexed Access Method utility program can- 
not be exceeded. If an attempt is made to load a record 
after the last allocated record area has been filled^ an 
end-of-file condition is returned. 

Only one user can have a data set connected for LOAD at any 
time. Other processing requests can concurrently be made 
to a data set that is being loaded. However » an attempt to 
retrieve a record from a data block being loaded can result 
in a no-record-found condition. You can load an indexed 
file from a sequential data set by using the load command 
(LO) of the Indexed Access Method utility program 



Initiate the processing of an indexed data set with a 
PROCESS request. After the PROCESS, any of the following 
functions can be requested. Note that the update functions 
require more than one request. 

• Direct reading - Retrieval of a single record inde- 
pendent of any previous request 

• Sequential reading - Retrieval of the next logical 
record from the point of the previous request 

• Direct updating - Retrieval of a single record for the 
purpose of updating that record; subsequent completion 
of the update by replacing or deleting the original 
record. 

• Sequential updating - Retrieval of the next logical 
record for the purpose of updating that record; subse- 
quent completion of the update by replacing or delet- 
ing the original record 
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Direct Reading 



• Inserting - Placement of a single record in its log- 
ical key sequence in the indexed data set 

• Deleting - Direct removal of a single record from the 
indexed data set 

• Extracting - extract data describing the data set 

Uhen the function is complete^ another function can be 
requested^ except that a sequential function can be fol- 
loued only by another sequential function until the 
sequence is ended. At any time» you terminate the process- 
ing by issuing a DISCONN. 



Use the GET request to read a record using direct access. 
The KEY parameter is required and must be the address of a 
field of full key length regardless of the KLEN (key 
length) specification. 

The record retrieved is the first record in the data set 
that satisfies the search argument defined by the KEY, 
KLEN, and KREL (key relation) parameters. The key field is 
updated to reflect the key in the record that satisfied 
the search. 

If KLEN is specified as less than full key length, only 
part of the key field is used for comparison when search- 
ing the data set. For example, suppose the keys in the 
data set are AAA, AAB, ABA, and ABB and suppose the key 
field contains ABO and KREL (key relation) is EQ . 

If KLEN is zero, the search argument is the full key (de- 
fault) ABO and a 'record not found* code is returned. If 
the KLEN specification is 2, the search argument is AB, 
and the third record is read. If the KLEN specification is 
1, the search argument is A, and the first record is read. 



Pi rect Updati ng 



To update a record using direct access^ 

1. Retrieve the record with a GET request with one of the 
update MODE/KREL parameters specified. 

2. Modify the record in your buffer as desired. However, 
do not change the key field in the record. Return the 
updated record to the data set with a PUTUP request. 






^mnit^^^ 
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Alternatively, you can delete the record with PUTDEL, or 
leave it unchanged by completing the update with a RELEASE 
request. 

A direct update, like a direct read, requires that the KEY 
parameter be specified as the address of a field of full 
key length. This field must not be modified during the 
update. 

The only valid requests, other than DISCONN and EXTRACT, 
that can follow GET for direct update are the requests that 
complete the update: 

• PUTUP 

• PUTDEL 

• RELEASE 

During the update, the subject record is locked; that is, 
the record is unavailable to any other request until the 
update is complete. Even if no other action is taken after 
the GET, the RELEASE is required to release the lock on the 
record. 






Sequential Reading 



o 



Use the GETSEQ request to read a record using sequential 
access. After a sequence has been initiated by a sequen- 
tial retrieval, only sequential functions can be 
requested until the sequence is completed with an end-of- 
data condition or an ENDSEQ request. At any time in the 
sequence, processing can be terminated with a DISCONN. 
Also, the sequence is terminated if any error or warning 
is returned while in sequential mode. 

Starting the Sequence. To begin the sequence with the 
first record in the data set, set the KEY address to zero. 
To start the sequence with any other record, specify a 
search argument as for a direct read. 

If you specify the search argument when you start the 
sequence, the key field is modified to reflect the key 
found as a result of the retrieval of the first record. 

Intermediate Retrievals. After the first retrieval, a 
GETSEQ retrieves the next sequential record regardless of 
any KEY, KREL, or KLEN specification. Therefore, you can 
use the same GETSEQ statement in a loop to read all the 
records in the sequence. If you specify a search argument 
on intermediate retrievals, it is ignored and the key 
field is not modified on intermediate retrievals. 
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Ending the Sequence. To end the sequence before the end of 
data is reached^ specify ENDSEQ. The sequence is ended 
automatically at the end of data. An end-of-data condition 
occurs when an attempt is made to retrieve a record after 
the last record in the data set. 

If you specify the EODEXIT parameter in the PROCESS* it is 
not necessary to test for the end-of-data return code. 
Mhen the end-of-data condition occurs* control transfers 
to your end-of-data routine. 



Sequent-jal Updating 



Inserting 



To update a record using sequential access* retrieve the 
record with a GETSEQ request with one of the update 
MODE/KREL parameters specified. The sequential retrieval 
for update is the same as the sequential read. A search 
argument is used only on the first retrieval of a sequence 
and is not specified if the sequence is to begin with the 
first record in the data set. The sequence is terminated 
with an ENDSEQ or with an end-of-data condition. 

The sequential update is completed in the same way as a 
direct update. The key in the record cannot be modified. 
The record can be returned to the data set with a PUTUP* 
deleted with a PUTDEL* or left unchanged by specifying 
RELEASE. Uhen the update is complete* another sequential 
read or update can be requested. 

It is valid to terminate the sequence with ENDSEQ* or tei — 
minate processing with a DISCONN either before or after 
completing the update. Figure 13 summarizes the protocol 
for sequential processing. 



To insert -a new record in a data set connected for proc- 
essing* specify PUT. The Indexed Access Method uses the 
key within the record in your buffer to insert the record 
in proper key order in the data set. 

The key of the inserted record must be different from any 
key in the data set* otherwise a duplicate key error 
occurs. The key can be higher than any key in the data 
set; that is* it is permissible to insert a record with a 
new hi gh key. 
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A request for sequential update: 




GET for update 




can be folloMed by: 




1. A request to end processing: 




DISCONN 




2. An end-of-data condition: 


End-of-sequence can be followed 


automatic end-of-sequence and 


by: 


transfer of control to EODEXIT 




routine 


1. A request to end processing: 




DISCONN 


3. A request to end the sequence: 




ENDSEQ 


2. Any processing function: 




GET, PUT, DELETE 


A request to complete the update: 


The completed update can be 




folloMed by: 


4. PUTUP 






1. A request to end processing: 


5. PUTDEL 


DISCONN 


6. RELEASE 


2. A request to end the sequence: 




ENDSEQ 




3. A sequential request: 




GETSEQ 



Figure 13. Protocol for Sequential Updating 



If there is no free space in the area associated with the 
insert or no blocks in the free pool, a no-more-space con- 
dition occurs. The no-more-space condition does not mean 
the data set is full; there can be free space in unrelated 
blocks. It indicates a need for data set reorganization. 
This procedure is described in "Reorganization" on page 
69. 



Deleting 



o 



Use DELETE to delete a record from the data set. The full 
key of the record must be specified. If there is no record 
with that key, a negative return code gives a warning. 

Deletion is also performed as part of updating by follow- 
ing a GET for update with a PUTDEL request. 
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Extract] ng 



You can extract information about a data set from the file 
control block (FCB). This includes information such as key 
length* key di splacement* block size» record size, and 
other detailed data regarding the data set structure. 

This data is requested by EXTRACT. Execution of this func- 
tion causes copying of the file control block to the spec- 
ified user area. You must provide the storage into uihich 
the data is copied. The data set must be connected by LOAD 
or PROCESS. 



HANDLING ERRORS 



All executed Indexed Access Method requests return a 
signed number* called a return code, in the task code word 
(referred to by task name) of the TCB. The return code 
reflects the condition of the requested function. Return 
codes are grouped in three categories^ 

• -1 - Successful completion 

• Posi ti ve - Error 

• Negative - Warning 



Error Exit Routine 



In PROCESS and LOAD requests, the address of an error exit 
routine can be specified by the ERREXIT parameter. If 
specified, this routine is executed whenever this request 
or any subsequent Indexed Access Method request for the 
duration of this PROCESS or LOAD terminates with a posi- 
tive return code. 

If the address of an error exit routine is not specified, 
the next sequential instruction after the request is exe- 
cuted regardless of the value of the return code. 



System Function Return Codes 



If a system function called by an Indexed Access Method 
request terminates with a positive return code, the return 
code is placed in a location reserved by the PROCESS or 
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LOAD request. This is used by any subsequent request until 
a DISCONN is issued. 

For example* GET uses the read function. If the read ter- 
minates with a positive return code^ that return code is 
saved in the location reserved for the system function 
return code in the PROCESS associated with the GET. The 
GET also terminates with a positive return code in the 
task control word that indicates a read error. The cause 
of the read error is determined from the system function 
return code. 



Data Set Shut Down 






Deadlocks 



o 



Sometimes an I/O error that is not associated with a spe- 
cific request occurs. For example^ Task A issues a GET on 
data set X. In order to secure buffer space, the Indexed 
Access Method writes out a block to data set Y and, in the 
process, an error occurs. Data set Y is damaged but there 
is no requesting program to accept an error return code. 

The error is recorded by setting the data-set-shut-down 
condition for data set Y. Uhen this condition exists, no 
requests other than a DISCONN are accepted for this data 
set. 

Later, if Task B issues a GET on data set Y, the request is 
terminated with a data-set-shut-down return code. Task B 
should issue a DISCONN and use recovery procedures to 
reconstruct the data set. An initial program load (IPL) 
cancels the data-set-shut-down condition. 



Since the Indexed Access Method uses record and block 
locks to preserve file integrity, deadlock condi ti ons are 
possible. A deadlock is a condition where two or more 
tasks interact in such a way that one or more resources 
become permanently locked and further progress is not pos- 
sible. 

A deadlock can also occur when two lACBs from the same 
task request a lock on the same record or a lock on the 
same block in sequential mode. 

In this section, the term deadlock refers not only to a 
true deadlock, but also to an apparent deadlock, in which 
a task holds a resource for an unreasonably long period of 
time. 
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Application tasks should not use the Indexed Access Method 
in such a utay that a record or block remains locked for a 
long period of time, since other tasks may attempt to use 
the same record or block. In a terminal oriented system, 
make every effort to ensure that a record or block is not 
locked during operator "think" time. Specifically, you 
should attempt to folloM these rules^ 

• Do not retrieve a record for update, display the 
record at the terminal, then wait for the operator to 
modify it before completing the update. 

• Do not retrieve a record in sequential mode, display 
the record at the terminal, then wait for an operator 
response before continuing the sequential operation. 

In both of these cases, a record or block is locked during 
operator "think" time and could be held for minutes or 
hours. 

Every effort should be made to avoid a deadlock situation. 
There is no way to break a deadlock except to release the 
locks that are being waited on. Even terminating the tasks 
involved might not break the deadlock because termination 
processing cannot occur until sny outstanding requests 
issued by a terminating task have completed. 



EXECUTING THE APPLICATION PROGRAM 



Application programs that use the Indexed Access Method 
are executed the same as other application programs. 
Because the Indexed Access Method and the indexed data 
sets are resources available to all tasks, delays can 
occur under heavy system usage. Specifically, with more 
than one task using the Indexed Access Method there can be 
contention between tasks for any of these resources^ 

• Entire indexed file 

• Index block in the data set 

• Data block in the data set 

• Data record in the data set 

• Buffer space from the system buffer pool 

For example, during the execution of a request from Task A, 
some buffer space can be required and an index block or 
data block or record can be locked (made unavailable to 
other requests). If a request from Task B requires more 
buffer space than remains available or if it requires a 
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locked block or records that request is delayed until the 
required resource is freed. 

In general » resources required by the Indexed Access Meth- 
od are allocated only for the duration of that request. 
There are two exceptions^ 

• During an update^ when control returns to the task 
after a GET or GETSEQ for update> the subject record is 
locked. The lock is released when the update is com- 
pleted with a PUTUP, PUTDEL, RELEASE, or by a DISCONN. 

• During sequential processing, when control returns to 
the task after a GETSEQ, the block containing the sub- 
ject record is locked and held in the buffer. 

Subsequent GETSEQ requests pick up records directly 
from the buffer; sequential processing is fast because 
no search is required. Ulhen a GET requires a record 
from the next block, the current block and buffer are 
released. Pending requests for buffer area are satis- 
fied and the next block is locked and held in the buff- 
er. Except for momentary release of the buffer area 
between blocks, one block and buffer are locked for 
the entire sequence. The sequence is terminated by an 
end-of-data condition, by an ENDSEQ, or by a DISCONN. 

The update and the sequence should be completed promptly. 
Use the following guidelines to avoid problems with these 
resources. 

1- Disconnect all indexed data sets before task termi- 
nation. The DISCONN releases locked records or blocks 
and writes out buffers for that data set that have not 
already been written. 

2. With multiple Indexed Access Method users on the sys- 
tem, use direct access rather than sequential access 
to retrieve a sequence of records interactively. A 
suggested method is: 

a. Retrieve the first record by key. 

b. Extract the key from that record and save it for 
the next retrieval. 

c. Retrieve the next record using the saved key and a 
greatei — than key relation. 

d. Repeat the second and third steps for the duration 
of the sequence. 
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HAINTAINING THE INDEXED DATA SET 



The Indexed Access Method does not provide specific pro- 
grams to perform indexed data set backup and recovery, nor 
does it include services to delete the data set or dump to 
the printer. These procedures are readily provided by a 
combination of EDX and Indexed Access Method services as 
suggested beloN. The Indexed Access Method utility pro- 
gram provides services to help you reorganize your data 
set as described beloN. 



Backup and Recovery 



Recovery Without Backup 



If you do not use the backup procedures outlined above and 
you encounter a problem with your data set» you still may 
be able to recreate your file. However* the status of 
requests made prior to the problem is uncertain. 

To recreate your data set, follow the steps given below as 
a method of reorganizing your data set. After recreating 
the data set, verify the status of requests made at the 
time the problem occurred. 



ff' 



To protect against the destruction of data, at regular 
intervals you should make a copy of the indexed data set 
(or the logical volume in which the data set exists) using 
the system COPY utility. During the interval between 
copies, you should keep a journal file of all transactions 
made against the indexed data set. 

The journal file can be a consecutive data set containing 
records that describe the type of transaction and the pei — 
tinent data. A damaged indexed data set can be recovered 
by updating the backup copy from the journal file. U J 

For example, suppose an indexed data set named REPORT is 
lost because of physical damage to the disk. The condition 
that caused the error has been repaired and the data set 
must be recovered. Delete REPORT and copy the backup vei — 
si on of REPORT to the desired volume. 

If a data set shut down condition exists, IPL again. Then 
issue a PROCESS to the REPORT data set and, using the 
journal file, recreate the transactions that occurred 
since the backup copy was made. 
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Reorqanizati on 






Dumping 



An indexed data set must be reorganized i«jhen required 
inserts fail because of lack of space. This condition does 
not imply that there is no more space in the data set; it 
means that there is no space in the srcB uhere inserts 
must be made. Therefore* you can reorganize without 
increasing the size. The following steps provide a method 
of performing a reorgani zati on^ 

1. Ensure that all outstanding requests against the data 
set have been completed; issue a DISCONN for every 
current lACB. 

2. Use the define command (DF) of the Indexed Access 
Method utility program to define a new indexed data 
set. Carefully estimate the number of base records and 
the amount and mix of free space in order to minimize 
the need for future reorganizations. Guidelines for 
making these estimates appear at the beginning of this 
chapter. 

3. Use the reorganize command (RO) of the Indexed Access 
Method utility program to load the new indexed data 
set from the indexed data set to be reorganized. 

Alternatively* you can use the unload command (UN) of 
the Indexed Access Method utility program to transfer 
the data from an indexed data set to a sequential data 
set, then use the load command (LO) to load it back 
into the indexed data set. The result is a reorganized 
indexed data set. 

^. Use system utilities to perform any desired house- 
keeping operations. The old data set can be deleted, 
and the new data set can subsequently be renamed to the 
name of the old data set. 



To print user records, retrieve the records sequentially 
and print them. Use the DP command of the $DISKUT2 utility 
for a hexadecimal dump of the entire data set including 
control information, index blocks, and data blocks. 
Information on the $DISKUT2 utility can be found in the 
Utilities, Operator Commands and Program Preparation 
manual . 
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Delete an indexed data set in the same manner in uhich you 
delete any data set. From your terminals use the DE com- 
mand of the $DISKUT1 utility (see the Uti li ties^ Operator 
Commands and Program Preparation manual). 



DATA SET FORMAT 



o 



BLOCKS 



The define command of the Indexed Access Method utility 
program formats and creates the indexed data set. The 
information required to determine the format and the num- 
ber of blocks in the data set is provided by ten parame- 
ters. These parameters are specified using the setparms 
command. Examples in this chapter use the following values 
for the parameters? 

parameter Name Value Addressed bv Parameter 



BLKSIZE 

RECSIZE 

KEYSIZE 

BASEREC 

FREEREC 

FREEBLK 

RSVBLK 

RSVIX 

FPOOL 

DELTHR 



Block size = 256 bytes 

Record size = 80 bytes 

Key size = 28 bytes 

Number of base records = 1000 

Number of free records per block = 1 

Percentage of free blocks = 10 

Percentage of reserved blocks = 10 

Percentage of reserved index = 10 

Percentage of free pool = 50 

Percentage of blocks to retain when 
deleting records; this value is allowed to 
default. 



\4 V 



The indexed data set is composed of a number of fixed 
length blocks. The block is the unit of data transferred 
by the Indexed Access Method, and is a multiple of 256. A 
block is addressed by its relative block number (RBN) such 
that the first block in the data set is located at RBN 0. 
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Note that the RBN is a block number used only in indexed 
data sets^ by the Indexed Access Method. A block as used 
in the Indexed Access Method differs from an EDX record in 
the following Nays: 



1. The size of a block is not limited to 256 bytes. Its 
length can be a multiple of 256 bytes. 

2. The RBN of the first block in an indexed data set is 0. 
The record number of the first EDX record in a data set 
is 1. 

The size» in 256-byte records* of the data set is calcu- 
lated by the define command of the Indexed Access Method 
utility program and returned to the terminal. 

There are three kinds of blocks in an indexed data sets a 
file control block (FCB)» index blocks* and data blocks. 
These blocks are all the same length* as defined by 
BLKSIZE* but they contain different kinds of information? 
control information* index entries* and data records. The 
control information is contained in block headers and the 
FCB* for a description of control information* see Figure 
14. Figure 14 shouis examples of the three block types. 
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Figure 14. Indexed Data Set Block Types 
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fCB 



Index Block 



Data Block 



The file control block (FCB) is the first block in the 
data set (RBN 0). It contains a fixed amount of control 
information. 



An index block contains a header followed by a number of 
index entries. Each index entry is a key-pointer pair. The 
key is the highest key associated with a block; the point- 
er is the RBN of that block. The number of entries con- 
tained in each index block depends on block size and key 
size. The header of the block is 16 bytes. The RBN field 
in each entry is 4 bytes. The key field in each entry must 
be an even number of bytes in length; if key size is odd 
then the field is padded with one byte to make key entry 
even. The number of index entries in an index block is^ 

block size - 16 
4 + key length 

The result is truncated; any remainder represents the num- 
ber of unused bytes in the block. For example^ if block 
size is 256 and key size is 28, then each index entry is 32 
bytes» there are 7 entries in a block, and the last 16 
bytes of the block are/ unused. 



A data block contains a header followed by a number of 
data record areas. The number of records that can be con- 
tained in a data block depends on block size and record 
size. The header of the block is 16 bytes. The number of 
record areas in the block is' 

block size - 16 
record size 

The result is truncated; any remainder represents the num- 
ber of unused bytes in the block. For example, if block 
size is 256 and record size is 80, there can be 3 records 
in a data block. In this example, there is no unused area. 
The key field of the last record slot in a data block 
indicates the high key for the data block. If all records 
of the data block are not currently used, the key field of 
the last record slot is normally the same as the key field 
of the last used record in the block. However, it is pos- 
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sible for the key field of the last record slot to contain 
a key higher than that of any record in the block. This 
can occur if the last record of the block has been 
deleted. Thus, deletion of a record does not reduce the 
key range for the block. 



The Index 



The index of an indexed data set is constructed in several 
levels so that, given a key, there is a single path (one 
index block per level) cascading through the index levels 
that leads to the data block associated with that key. The 
index is built from the bottom up. At the lowest level are 
the prime index blocks. At the second level are index 
blocks containing entries that point to the prime index 
blocks. There are enough levels so that the highest level 
consists of a single index block. 



Prime Index Blocks 



o 



Entries in a prime index block point to data blocks. Each 
entry in a prime index block is one of three possible 
typesJ 

• Allocated (used) entry. This type of entry points to 
an active data block. The key portion of the entry is 
initialized to binary I's (all bits on). The key 
portion of the entry contains the highest key from the 
data block. The pointer portion contains the RBN of 
the data block. Allocated entries are the first 
entries in the index block. The number of index 
entries initially allocated when the indexed data set 
is loaded is calculated as the total number of entries 
per index block, less the number of entries of the oth- 
er two types (free block entry and reserve block 
entry) (see Figure 15). 

• Free block entry. This type of entry points to a free 
data block. The key portion of the entry contains 
binary zeros. The pointer portion contains the RBN of 
the free block. Free block entries follow the allo- 
cated entries in the index block. The number of index 
entries initially formatted as free entries when the 
indexed data set is loaded is the specified percentage 
(FREEBLK) of the total number of entries, with the 
result rounded up if there is a remainder. 
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Figure 15. Example of Prime Index Block 



• ''^Reserve block entry. This type of entry does not point 
to a block. It is reserved for later use as a pointer 
to a data block which can be taken from the free pool. 
Both the key and pointer portions of a reserve block 
entry are binary zeros. Reserve block entries are at 
the end of the index block. Uhen a reserve block entry 
is converted to a used entry, the index block is refoi — 
matted to move the entry to the allocated entry area of 
the block. The number of index entries initially fo» — 
matted as reserve block entries is the specified pei — 
centage (RSVBLK) of the total number of entries, with 
the result rounded up if there is a remainder. Howev- 
er, if the number of free block entries and the number 
of reserve block entries together require all index 
entries, the number of reserve block entries is 
reduced by 1. This provides at least one allocated 
entry per index block. 

In order to calculate the number of prime index blocks in 
an indexed data set, you must first know the initial number 
of data blocks allocated in the indexed data set. The ini- 
tial number of data blocks is calculated as the specified 
number of base records (BASEREC) divided by the number of 
allocated (not free) records in a data block, with the 
result rounded up if there is a remainder. The number of 
prime index blocks can then be calculated as the initial 
number of allocated data blocks divided by the number of 
allocated entries per prime index block, with the result 
rounded up if there is a remainder. 
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Second-level Index Block 






Entries in a second-level index block point to prime index 
blocks. Each entry in a second-level index block is one of 
tMO possible types: 

• Allocated (used) entry. This type of entry points to 
an existing prime index block. The key portion of the 
entry is initialized to binary I's (all bits on). The 
key portion of the entry contains the highest key from 
the prime index block. The pointer portion contains 
the RBN of the prime index block. Allocated entries 
&re the first entries in the index block. The number of 
index entries initially allocated uhen the indexed 
data set is loaded is calculated as the total number of 
entries per index blocks less the number of reserve 
index entries. 

• Reserve index entry. This type of entry does not point 
to a block. It is reserved for later use as a pointer 
to a prime index block that can be taken from the free 
pool. Both the key and pointer portions of a reserve 
index entry are binary zeros. Reserve index entries 
are at the end of the index block. The number of index 
entries initially formatted as reserve index entries 
is the specified percentage (RSVIX) of the total num- 
ber of entries, with the result rounded up if there is 
a remainder. However, if the number of reserve index 
entries is the same as the total number of entries in 
an index block, the number of reserve index entries is 
reduced by 1. This provides at least one allocated 
entry per second-level index block. 

The number of second-level index blocks is calculated as 
the number of prime index blocks divided by the number of 
allocated entries per second-level index block, with the 
result rounded up if there is a remainder (see Figure 16). 



Higher Level Index Block 



Entries in a higher level index block point to index 
blocks at the next lower level. All entries in higher lev- 
el index blocks are allocated (used) entries. The key 
portion of the entry contains the highest key from the 
next lower level index block. The pointer portion contains 
the RBN of the next lower level index block. The number of 
blocks at any higher index level is calculated as the 
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Figure 16. Example of Second-Level Index Block 



number of index blocks at the next lower level divided by 
the total number of entries per index block, with the 
result rounded up if there is a remainder (see Figure 17). 

If the number of index blocks at any level is one, that 
level is the top level of the index. Although the Indexed 
Access Method is capable of supporting 17 levels of index, 
anv given indexed data set is formatted with only as many 
index levels as are required for the specified number of 
records- If an indexed data set has not been fully loaded, 
it is possible that one or more higher index levels are 
not yet required, even though they exist in the file 
structure. In this case, the unnecessary higher levels are 
not used. 



Index Example 



In the sample data set described at the beginning of this 
chapter, 500 data blocks are initially allocated to the 
data set. Each prime index block contains one free block 
entry, one reserve block entry, and five allocated 
entries; therefore, the total number of prime index blocks 
is 100. Each second-level index block contains one reserve 
index entry and six allocated entries; therefore, the num- 
ber of second-level index blocks is 17. The number of 
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Figure 17. Example of Highei — Level Index Block 



r...,^ 



entries in higher level index blocks is seven. This 
results in three index blocks at the third level and one 
at the fourth level. 



Cluster 



Therefore the sample data set contains a total of 121 
index blocks. Of these blocks, 100 ar& prime index and the 
remaining 21 &re high-level index blocks. This dis- 
tinction is important because, as shoNn later in this 
chapter, high-level index blocks are located contiguously 
at the beginning of the data set (after the FCB), while 
prime index blocks are scattered throughout the file with 
the data blocks. Figure 18 shows the structure of the 
high-level index blocks. 



Data records are loaded into the data blocks in ascending 
order by key. Each data block is pointed to by a prime 
index block entry that contains the high key of the data 
block (that is, the key from the last record slot in the 
data block) . 



o 



Prime index blocks and data blocks are stored together in 
the data set in groups called clusters . Each cluster 
begins with a prime index block followed by as many data 
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Figure 18. High-Level Index Block Structure 



blocks as there are allocated or free entries in the index 
block. Data blocks can be of two types* allocated data 
blocks and free data blocks. The prime index block can 
also contain unused slots for reserved blocks. For exam- 
ple» if there are seven entries in an index blocks there 
&r^ eight blocks in a cluster^ one prime index block fol- 
lowed by up to 7 data blocks. If there are reserve blocks 
specified, even though the cluster can expand to eight 
blocks, the blocks represented by the reserve block 
entries &r^ not included until insert activity has taken 
place and the required blocks have been obtained from the 
free pool. For example, if there are seven entries in an 
index block, and one of the entries is a reserve block 
entry, then there would only be seven blocks in the clus- 
ter initially (one index block and six data blocks). This 
is illustrated by the following diagram. 
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Uihen an indexed data set is loaded with data records, free 
space is reserved for records that may be inserted during 
processing. There &r^ four kinds of free space: free 
records, free blocks, reserve blocks, and reserve index 
blocks. 
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Free Records 



Free records are areas reserved at the end of each data 
block. The FREEREC parameter of define command of the 
Indexed Access Method utility program specifies the num- 
ber of free records that are reserved in each data block. 
The remaining record areas are called allocated records. 
For example^ if a block contains three data record areas 
and you specify one free record per block, then there are 
two allocated records per block. See Figure 19. 

Ulhen records &re loaded, the allocated records are filled, 
and the free records ar& skipped over. During processing, 
a record can be inserted in a block that contains a free 
record. 
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Figure 19. Example of a data block 
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Free Blocks 



Free blocks follou the allocated data blocks Mithin each 
cluster. For example^ if the cluster contains six data 
blocks and you specify 10 as the percentage of free 
blocks^ then there are five allocated blocks and one free 
block in each cluster. 
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Uhen records are loaded^ the allocated record areas in the 
allocated data blocks are filled* and the free blocks are 
skipped over. During processing* as data blocks become 
full* a free block can be included in the logical block 
sequence to provide space for more insertions. 



Reserve Blocks 



Reserve blocks do not exist in the cluster. When all data 
blocks in a cluster are used and another data block is 
needed* a data block can be created from the free pool* 
provided the prime index block contains a reserve block 
entry. In this case* the reserve block entry in the prime 
index block points to the block* and the data block 
becomes a normal used data block. 



o 



Reserve Index Entries 



Reserve index entries in second-level index blocks alloM 
the index structure to be expanded by adding new prime 
index blocks. These* in turn* can have data blocks associ- 
ated with them* thus forming new clusters. This process of 
forming a new cluster is sometimes called a cluster split . 

The initial number of allocated data blocks in the data 
set can be calculated as the specified number of base 
records (BASEREC) divided by the number of allocated (not 
free) records in a data block* with the result rounded up 
if there is a remainder. 



The number of clusters in the data set can be calculated 
as the initial number of allocated data blocks divided by 
the number of allocated entries in each prime index block* 
with the result rounded up if there is a remainder. 
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The total number of free blocks in the data set (not 
including the free pool) is calculated as the number of 
clusters in the data set multiplied by the number of free 
entries in each prime index block. 



The last Cluster 






The last cluster in the data set may be different from the 
other clusters. It contains the same number of free blocks 
as the other clusters but only enough allocated blocks to 
accommodate the records that you have specified with the 
parameter BASEREC. 

For example^ suppose you intend to load 1000 records in an 
indexed data set that is formatted for two allocated 
records and one free record per block and five allocated 
blocks and one free block per cluster. The number of allo- 
cated blocks in a data set isJ 

number of base records 



number of allocated records per block 



The number of allocated blocks in this example is 1000/2 
or 500 blocks. The number of clusters in a data set is? 

number of allocated blocks 



number of allocated blocks per cluster 



The number of clusters in this example is 500/5 or 100 
clusters. Note that in both these calculations, if the 
quotient is not an integer, it must be rounded up (rather 
than truncated) in order to accommodate all of the base 
records. Thus, in the last allocated block, there can be a 
few more allocated records than required. However, the 
last cluster can be a short cluster because it will have 
only the required number of allocated blocks. 

In this example, the number of allocated blocks divided by 
the number of allocated blocks per cluster (500/5) equals 
100 with no remainder. If there is remainder it represents 
the number of allocated entries in the prime index block 
for the last cluster, thus the number of allocated data 
blocks in that cluster. Unused entries in the last prime 
index block are treated as reserve block entries. 



Sequential Chaining 



Data blocks in an indexed data set are chained together by 
forward pointers located in the headers of data blocks. 
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free Pool 



Only allocated data blocks are included in this sequential 
chain. Free blocks &rQ skipped over. This provides effi- 
cient sequential processing of the data set with no need 
to reference the index. Uhen a free block is converted to 
an allocated blocks it is included in the chain. 



If you specify that you want a free pool (by the FPOOL 
parameter of define command of the Indexed Access Method 
utility program) y your indexed data set contains a pool of 
free blocks at the end. The file control block contains a 
pointer to the first block of the free pool> and all 
blocks in the free pool are chained together by forward 
pointers. 

A block can be taken from the free pool chain to become 
either a data block or a prime index block. Uhen this is 
done/ the block is taken from the beginning of the chain* 
and its address (RBN) is placed in the appropriate prime 
index block (if the new block is to become a data block) 
or in the second level index block (if the new block is to 
become a prime index block). Any block in the free pool 
can be used as either a data block or as a prime index 
block. 

Ulhen a data block becomes empty because of record 
deletions* it is sometimes possible to return it to the 
free pool (depending on the delete threshold (DELTHR) 
parameter). Uhen this is done* reference to the block is 
removed from the prime index block* and the block is 
placed on the beginning of the free pool chain. Index 
blocks are never returned to the free pool. 

The calculation of the initial size of the free pool con- 
sists of several steps* as follows^ 

• Each reserve block entry in a prime index block 
represents a possible use of a data block from the free 
pool. The 'number of data blocks that can be assigned to 
initial clusters is the number of prime index blocks 
times the number of reserve block entries in each 
prime index block. 

• Each reserve index entry in a second-level index block 
represents a possible use of a prime index block from 
the free pool. The number of prime index blocks that 
can be assigned from the free pool is the number of 
second-level index blocks times the number of reserve 
index entries in each second-level index block. 
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Each prime index block taken from the free pool con- 
sists entirely of empty (reserve block) entries. NeN 
data blocks can then be taken from the free pool for 
these entries in the new prime index block. The total 
number of such data blocks is the total number of 
entries per index block times the number of new prime 
index blocks (calculated in the previous step). 

The maximum number of blocks that can conceivably be 
taken from the free pool is the sum of the above three 
calculations. This is the maximum possible free pool. 

The actual number of blocks in the free pool is the 
specified percentage (FPOOL) of the maximum possible 
free pool^ with the result rounded up if there is a 
remainder. 



STORAGE AND PERFORMANCE INFORMATION 



STORAGE REQUIREMENTS 



The minimum amount of storage required by the Indexed 
Access Method to perform all functions is about 14KB» not 
including the link module or the user error exit routine. 
This is based on the following assumptions* 

• A maximum block size of 256 bytes for any indexed data 
set. Since the buffer must be large enough for two 
blocks^ we have assumed a 512 byte buffer. If your max- 
imum block size is larger* you should subtract the 512 
and add in double your block size. You can improve pei — 
formance by making the buffer larger. 

• One user connected to an indexed file at a time. If you 
will have more than one user connected* you should add 
about 625 bytes per additional user. 

The IBM-supplied link module is included in your applica- 
tion program (see Figure 12). Its size is about 250 bytes. 



INDEXED FILE SIZE 



The structure of an indexed file is highly dependent on 
parameters you specify when you create the file. This is 
described in "Data Set Format" on page 70. The calcu- 
lations presented there are summarized in "Summary of 
Calculations" on page 84. 
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PERFORMANCE INFORMATION 



Performance of the Indexed Access Method is primarily 
determined by the structure of the indexed data set being 
used. This structure is determined by parameters you spec- 
ify when you create the data set. This is described in 
"Data Set Format" on page 70. Performance is affected by 
file structure in the following ways: 

• File size. A large file spans more cylinders of the 
direct access device* so the average seek to get the 
the record you want is longer. 

• Number of index levels. A file with many index levels 
requires more accesses to get to the desired data 
record* thus degrades performance. Factors which 
influence the number of index levels are' 



Number of records in data set. 

Amount and type of free space. 

Block size. 

Key size. 

Data record size. 

To get a feeling for the affect of the various parameters 
on the file structure* you should calculate several exam- 
ples. Refer to "Summary of Calculations." 

In addition to file structure* the following factors also 
influence performance* 

• Buffer size. If you provide a large buffer when you 
install the Indexed Access Method* it is more likely 
that blocks (especially high-level index blocks) 
needed are already in storage and need not be recalled 
from the data set. 

• Contention. If many tasks are concurrently using the 
Indexed Access Method* interference can result* and 
performance is degraded. 



V^^ 



SUMMARY OF CALCULATIONS 



The following calculations are used to structure an 
indexed data set. In the calculations requiring division* 
results with non-zero remainders are either^ 



o 
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truncated 



or rounded up 



To truncate is to drop the remainder; to round up is to 
add one (only if the remainder is non-2ero)» and truncate. 



Data Block 

Records per data block 
= block size minus 16» 
divided by record size; 
result truncated. 



= (BLKSIZE-16)/RECSIZE 



Free records per block. 



= FREEREC 



Allocated records per 
data block = Records 
per block minus free 
records per block. 



3=1-2 



Index Block (General) 

Index entry size = key 
length plus 4; must be 
even — add 1 if odd. 






Total entries per index 
block = block size 
minus 16* divided by 
index entry size; 
result truncated. 



= KEYSIZE + ^ (+1 if odd) 



= (BLKSIZE-16) / 



^ T 



Index Block (PIXB) 

Free entries per 
primary index block 
(PIXB) = specified 
percentage of total 
entries per index 
block; result rounded 
up. 



= FREEBLK % of 



5 




U 



Reserve entries per 
PIXB = specified 
percentage of total 
entries per index block; 
result rounded up. 
If free entries per 
PIXB and reserve 
entries per PIXB require 
all PIXB entries, 
subtract one from 
reserve entries per PIXB, 



= RSVBLK y, of 



C-1 if 



u 










= 


5 
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Allocated entries per 
PIXB = total entries 
per index block minus 
free entries per PIXB» 
minus reserve entries 
per PIXB. 



8 


= 


5 


- 


6 


- 


7 



^ y 



Index Block (SIXB) 

Reserve entries per 
secondary index block 
(SIXB) = specified 
percentage of total 
entries per index 
block; result rounded 
up. If reserve entries 
per SIXB require all 
SIXB entries^ 
subtract one. 



= RSVIX *4 of 



5 




U 



(-1 if 



9=5 



10 



Allocated entries per 
SIXB = total entries 
per index block minus 
reserve entries per 
SIXB. 



10 


= 


5 


- 


9 



11 



Delete Threshold 

The number of blocks to 
retain in cluster 
(delete threshold) is 
calculated in one of 
three ways? 



V^' 



If the RSVBLK parameter 
Mas not specified: 
Number of blocks to 
retain in cluster = 
total entries per index 
block. 



11 


= 


5 



or 



b. If the RSVBLK parameter 
Mas specified^ but the 
DELTHR parameter Mas not 
speci f iedJ 
Number of blocks to 
retain in cluster = 
allocated entries per 
PIXB, plus one-half of 
free entries per PIXB; 
result rounded up. 



11 


= 


8 


+ 


6 


/ 2 


U 



or 



c 
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If the RSVBLK parameter 
uias specified^ and the 
DELTHR parameter was 
speci f i eds 
Number of blocks to 
retain in cluster = 
specified percentage of 
total entries per index 
block; result rounded 
up. If the result is 
zero^ set it to 1. 



11 



= DELTHR % of 



5 




U 



(If 0, set 



11 



to 1) 



12 



Data in Data Set 

Initial allocated data 
blocks = base records 
divided by allocated 
records per data block; 
result rounded up. 



12 



= BASEREC / 



3 




U 



13 



Number of clusters in 
data set = initial 
allocated data blocks^ 
divided by allocated 
entries per PIXB; 
result rounded up. 



13 


= 


12 


/ 


8 




U 



y 



14 



Total number of free 
blocks in data set = 
number of clusters in 
data set* times free 
entries p^r PIXB. 



14 


= 


13 


M 


6 



Indexes in Data Set 

Number of primary 
index blocks (PIXBs) 
= number of clusters 
in data set. 



15 



15 


= 


13 



16 



Number of secondary 
index blocks (SIXBs) 
= number of PIXBs» 
divided by allocated 
entries per SIXB; 
result rounded up. 



16 


= 


15 


/ 


10 




U 
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17 



Calculate the number 
of index blocks for 
levels 3 to n. Note 
that levels 1 (PIXB) 
and 2 (SIXB) have 
already been calculated. 
Ulhen the number of 
index blocks at a 
level is 1, n has 
been reached and the 
calculation is finished. 



o 



Number of index blocks 
at level i (i=3 to n) = 
number of index blocks 
at next loMer level> 
divided by total entries 
per index block; result 
rounded up. 



17 


i 


17 



i-1 



5 




U 



18 



Total number of index 
blocks = sum of index 
blocks at each level 
until a level containing 
a single index block 
is attained. 



Free Pool 

Number of nei>i data 
blocks that can be 
assigned to existing 
clusters = reserve 
entries per PIXB» 
times number of PIXBs. 



19 



18 



15 



16 



+ (Sum of all 



17 



s) 



19 


= 


7 


¥c 


15 






20 



Number of new clusters 
(PIXBs) that can be 
created = reserve 
entries per SIXB> 
times number of SIXBs. 



20 


r 


9 


a 


16 



21 



Number of neui data 
blocks that can be 
assigned to new clusters 
= total entries p&r 
index blocks times 
number of new clusters 
that can be created. 



21 


= 


5 


X 


20 



o 
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22 



Maximum possible free 
pool = number of new 
data blocks that can 
be assigned to existing 
clusters* plus number 
of new clusters (PIXBs) 
that can be created, 
plus number of new data 
blocks that can be 
assigned to new clusters. 



22 


= 


19 


+ 


20 


+ 


21 



23 



Actual number of free 
pool blocks = specified 
percentage of maximum 
possible free pool; 
result rounded up. 



23 



= FPOOL % of 



22 




U 



2^ 



C 



Size of Data Set 

Total number of blocks 
in data set = 1 (for 
file control block), 
plus total number of 
index blocks, plus 
initial allocated data 
blocks, plus total 
number of free blocks 
in data set, plus actual 
number of free pool 
blocks. 



2^ 



= 1 + 



18 


+ 


12 








14 


+ 


23 
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